@pipedog/core 0.0.0 → 0.2.0

package/dist/turns/user_stop/external_user_turn_stop_strategy.js

@@ -0,0 +1,205 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_stop/external_user_turn_stop_strategy.py
+/** User turn stop strategy driven by another component in the pipeline. */
+import { Event, TimeoutError, waitFor } from "@pipedog/asyncio";
+import { InterimTranscriptionFrame, ProposedUserStartedSpeakingFrame, ProposedUserStoppedSpeakingFrame, TranscriptionFrame, UserStartedSpeakingFrame, UserStoppedSpeakingFrame, } from "../../frames/frames.js";
+import { logger } from "../../utils/logger.js";
+import { ProcessFrameResult } from "../types.js";
+import { BaseUserTurnStopStrategy, } from "./base_user_turn_stop_strategy.js";
+/**
+ * User turn stop strategy driven by another component in the pipeline.
+ *
+ * The end-of-turn counterpart to `ExternalUserTurnStartStrategy`, taking the
+ * same two signals:
+ *
+ * - `ProposedUserStoppedSpeakingFrame` — a service proposing that the turn has
+ *   ended. This strategy decides, and emits the `UserStoppedSpeakingFrame`
+ *   itself. It may also hold the turn open past the proposal, which is what
+ *   `waitForTranscript` does.
+ *
+ * - `UserStoppedSpeakingFrame` — the turn end was already decided and
+ *   announced elsewhere, typically by a shared `UserTurnProcessor`. This
+ *   strategy adopts that decision and emits nothing.
+ *
+ * To shift the timing further, subclass this strategy and override
+ * `BaseUserTurnStopStrategy.triggerUserTurnStopped`, which both paths reach
+ * once they decide the turn is over. Its `enableUserSpeakingFrames` option
+ * already carries whichever path got there, so pass it through when the
+ * override eventually finalizes.
+ */
+export class ExternalUserTurnStopStrategy extends BaseUserTurnStopStrategy {
+    _timeout;
+    _waitForTranscript;
+    _text = "";
+    _userSpeaking = false;
+    _seenInterimResults = false;
+    _turnAnnouncedElsewhere = false;
+    _turnOpen = false;
+    _event = new Event();
+    _task = null;
+    constructor(options = {}) {
+        super(options);
+        this._timeout = options.timeout ?? 0.5;
+        this._waitForTranscript = options.waitForTranscript ?? true;
+    }
+    /** Whether this strategy resolves proposals into turn stops. */
+    get resolvesProposedTurnStopFrames() {
+        return true;
+    }
+    /** Whether turn-stop signaling waits for transcript text. */
+    get waitForTranscript() {
+        return this._waitForTranscript;
+    }
+    set waitForTranscript(value) {
+        this._waitForTranscript = value;
+    }
+    /** Ready the strategy to detect the end of the turn now starting. */
+    async handleUserTurnStarted() {
+        await this._reset();
+        this._turnOpen = true;
+    }
+    /** Clear per-turn state once the turn has ended. */
+    async handleUserTurnStopped() {
+        await this._reset();
+        this._turnOpen = false;
+    }
+    /** Clear per-turn state. Runs at both turn boundaries. */
+    async _reset() {
+        this._text = "";
+        this._userSpeaking = false;
+        this._seenInterimResults = false;
+        this._turnAnnouncedElsewhere = false;
+        this._event.clear();
+    }
+    /**
+     * Set up the strategy.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    async setup(setup) {
+        await super.setup(setup);
+        this._task = this.createTask(() => this._taskHandler(), `${this}::_task_handler`);
+    }
+    /** Cleanup the strategy. */
+    async cleanup() {
+        await super.cleanup();
+        if (this._task) {
+            await this.taskManager.cancelTask(this._task);
+            this._task = null;
+        }
+    }
+    /**
+     * Process an incoming frame to update strategy state.
+     *
+     * Updates internal transcription text and speaking state. The user end
+     * turn will be triggered when appropriate based on the collected frames.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns Always returns CONTINUE so subsequent stop strategies are evaluated.
+     */
+    async processFrame(frame) {
+        if (frame instanceof ProposedUserStartedSpeakingFrame) {
+            await this._handleUserStartedSpeaking({ announcedElsewhere: false });
+        }
+        else if (frame instanceof ProposedUserStoppedSpeakingFrame) {
+            await this._handleUserStoppedSpeaking({ announcedElsewhere: false });
+        }
+        else if (frame instanceof UserStartedSpeakingFrame) {
+            await this._handleUserStartedSpeaking({ announcedElsewhere: true });
+        }
+        else if (frame instanceof UserStoppedSpeakingFrame) {
+            await this._handleUserStoppedSpeaking({ announcedElsewhere: true });
+        }
+        else if (frame instanceof InterimTranscriptionFrame) {
+            await this._handleInterimTranscription(frame);
+        }
+        else if (frame instanceof TranscriptionFrame) {
+            await this._handleTranscription(frame);
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+    /** Handle the external signal that the user is speaking. */
+    async _handleUserStartedSpeaking(options) {
+        this._userSpeaking = true;
+        this._turnAnnouncedElsewhere = options.announcedElsewhere;
+    }
+    /** Handle the external signal that the user has stopped speaking. */
+    async _handleUserStoppedSpeaking(options) {
+        this._userSpeaking = false;
+        this._turnAnnouncedElsewhere = options.announcedElsewhere;
+        await this._maybeTriggerUserTurnStopped();
+    }
+    async _handleInterimTranscription(_frame) {
+        this._seenInterimResults = true;
+    }
+    /** Handle user transcription. */
+    async _handleTranscription(frame) {
+        this._text += frame.text;
+        // We just got a final result, so let's reset interim results.
+        this._seenInterimResults = false;
+        // Reset aggregation timer.
+        this._event.set();
+    }
+    /**
+     * Asynchronously monitor transcriptions and trigger user end turn when ready.
+     *
+     * If transcription text exists and the user is not currently speaking,
+     * triggers the user end turn. Handles multiple or delayed transcriptions
+     * gracefully.
+     */
+    async _taskHandler() {
+        while (true) {
+            try {
+                await waitFor(() => this._event.wait(), this._timeout);
+                this._event.clear();
+            }
+            catch (e) {
+                if (!(e instanceof TimeoutError))
+                    throw e;
+                // Note: with waitForTranscript off (realtime mode) this fires on
+                // every tick. The _turnOpen check protects against unnecessarily
+                // triggering over and over (harmless, since the controller drops
+                // repeated triggers, but noisy).
+                if (this._turnOpen) {
+                    await this._maybeTriggerUserTurnStopped();
+                }
+            }
+        }
+    }
+    /**
+     * End the turn, emitting the turn frame unless it was already announced.
+     *
+     * Reads the flag rather than taking it as an argument: finalization can
+     * land here from the transcript timeout above, long after the signal that
+     * set it.
+     */
+    async _triggerUserTurnStopped() {
+        if (this._turnAnnouncedElsewhere) {
+            logger.debug(`${this}: adopting a user turn stop decided elsewhere`);
+        }
+        else {
+            logger.debug(`${this}: resolving a proposed user turn stop`);
+        }
+        await this.triggerUserTurnStopped({
+            enableUserSpeakingFrames: this._turnAnnouncedElsewhere ? false : null,
+        });
+    }
+    async _maybeTriggerUserTurnStopped() {
+        if (this._userSpeaking) {
+            return;
+        }
+        if (!this._waitForTranscript) {
+            // Fire as soon as the external stop signal arrives —
+            // transcripts (if any) are off the latency critical path.
+            await this._triggerUserTurnStopped();
+            return;
+        }
+        if (!this._seenInterimResults && this._text) {
+            await this._triggerUserTurnStopped();
+        }
+    }
+}
+//# sourceMappingURL=external_user_turn_stop_strategy.js.map

package/dist/turns/user_stop/index.d.ts

@@ -0,0 +1,10 @@
+export { BaseUserTurnStopStrategy, UserTurnStoppedParams, } from "./base_user_turn_stop_strategy.ts";
+export { DeferredUserTurnStopStrategy, deferred } from "./deferred_user_turn_stop_strategy.ts";
+export { EagerMatchPolicy, ExactMatch, NormalizedMatch } from "./eager_match_policy.ts";
+export { EagerUserTurnStopStrategy } from "./eager_user_turn_stop_strategy.ts";
+export { ExternalUserTurnCompletionStopStrategy } from "./external_user_turn_completion_stop_strategy.ts";
+export { ExternalUserTurnStopStrategy } from "./external_user_turn_stop_strategy.ts";
+export { LLMTurnCompletionUserTurnStopStrategy } from "./llm_turn_completion_user_turn_stop_strategy.ts";
+export { SpeechTimeoutUserTurnStopStrategy } from "./speech_timeout_user_turn_stop_strategy.ts";
+export { TurnAnalyzerUserTurnStopStrategy } from "./turn_analyzer_user_turn_stop_strategy.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/turns/user_stop/index.js

@@ -0,0 +1,15 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_stop/__init__.py
+export { BaseUserTurnStopStrategy, UserTurnStoppedParams, } from "./base_user_turn_stop_strategy.js";
+export { DeferredUserTurnStopStrategy, deferred } from "./deferred_user_turn_stop_strategy.js";
+export { EagerMatchPolicy, ExactMatch, NormalizedMatch } from "./eager_match_policy.js";
+export { EagerUserTurnStopStrategy } from "./eager_user_turn_stop_strategy.js";
+export { ExternalUserTurnCompletionStopStrategy } from "./external_user_turn_completion_stop_strategy.js";
+export { ExternalUserTurnStopStrategy } from "./external_user_turn_stop_strategy.js";
+export { LLMTurnCompletionUserTurnStopStrategy } from "./llm_turn_completion_user_turn_stop_strategy.js";
+export { SpeechTimeoutUserTurnStopStrategy } from "./speech_timeout_user_turn_stop_strategy.js";
+export { TurnAnalyzerUserTurnStopStrategy } from "./turn_analyzer_user_turn_stop_strategy.js";
+//# sourceMappingURL=index.js.map

package/dist/turns/user_stop/llm_turn_completion_user_turn_stop_strategy.d.ts

@@ -0,0 +1,44 @@
+/** User turn stop strategy gated on the LLM's turn-completion verdict. */
+import { type Frame } from "../../frames/frames.ts";
+import type { ProcessFrameResult } from "../types.ts";
+import { UserTurnCompletionConfig } from "../user_turn_completion_mixin.ts";
+import type { BaseUserTurnStopStrategyOptions } from "./base_user_turn_stop_strategy.ts";
+import { ExternalUserTurnCompletionStopStrategy } from "./external_user_turn_completion_stop_strategy.ts";
+export interface LLMTurnCompletionUserTurnStopStrategyOptions extends BaseUserTurnStopStrategyOptions {
+    /**
+     * Configuration applied to the LLM via the `filterIncompleteUserTurns`
+     * setting on `StartFrame`. Defaults to `new UserTurnCompletionConfig()`.
+     */
+    config?: UserTurnCompletionConfig | null;
+}
+/**
+ * LLM-gated stop strategy.
+ *
+ * Extends `ExternalUserTurnCompletionStopStrategy` with the LLM-specific setup
+ * needed for the marker-based completion protocol: on `StartFrame`, pushes an
+ * `LLMUpdateSettingsFrame` downstream that enables `filterIncompleteUserTurns`
+ * on the LLM and seeds the `UserTurnCompletionConfig`. The update is marked
+ * `reachInactiveServices` so that every LLM behind an `LLMSwitcher` is
+ * configured, not only the one active at startup.
+ *
+ * Finalization itself is inherited: when the LLM service's
+ * `UserTurnCompletionLLMServiceMixin` detects a `●` marker, it broadcasts a
+ * `UserTurnInferenceCompletedFrame` and the base class fires
+ * `on_user_turn_stopped`. On `incomplete_short` / `incomplete_long` markers
+ * the mixin re-prompts internally and no completion frame is emitted, so the
+ * public stop event stays deferred.
+ *
+ * Install alongside one or more `deferred(...)`-wrapped detector strategies
+ * that drive `on_user_turn_inference_triggered` but leave finalization to
+ * this strategy.
+ */
+export declare class LLMTurnCompletionUserTurnStopStrategy extends ExternalUserTurnCompletionStopStrategy {
+    protected _config: UserTurnCompletionConfig;
+    constructor(options?: LLMTurnCompletionUserTurnStopStrategyOptions);
+    /** Return the configured `UserTurnCompletionConfig`. */
+    get config(): UserTurnCompletionConfig;
+    /** Configure the LLM on start and delegate completion handling to the base. */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+    protected _configureLlm(): Promise<void>;
+}
+//# sourceMappingURL=llm_turn_completion_user_turn_stop_strategy.d.ts.map

package/dist/turns/user_stop/llm_turn_completion_user_turn_stop_strategy.js

@@ -0,0 +1,59 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_stop/llm_turn_completion_user_turn_stop_strategy.py
+/** User turn stop strategy gated on the LLM's turn-completion verdict. */
+import { LLMUpdateSettingsFrame, StartFrame } from "../../frames/frames.js";
+import { LLMSettings } from "../../services/settings.js";
+import { UserTurnCompletionConfig } from "../user_turn_completion_mixin.js";
+import { ExternalUserTurnCompletionStopStrategy } from "./external_user_turn_completion_stop_strategy.js";
+/**
+ * LLM-gated stop strategy.
+ *
+ * Extends `ExternalUserTurnCompletionStopStrategy` with the LLM-specific setup
+ * needed for the marker-based completion protocol: on `StartFrame`, pushes an
+ * `LLMUpdateSettingsFrame` downstream that enables `filterIncompleteUserTurns`
+ * on the LLM and seeds the `UserTurnCompletionConfig`. The update is marked
+ * `reachInactiveServices` so that every LLM behind an `LLMSwitcher` is
+ * configured, not only the one active at startup.
+ *
+ * Finalization itself is inherited: when the LLM service's
+ * `UserTurnCompletionLLMServiceMixin` detects a `●` marker, it broadcasts a
+ * `UserTurnInferenceCompletedFrame` and the base class fires
+ * `on_user_turn_stopped`. On `incomplete_short` / `incomplete_long` markers
+ * the mixin re-prompts internally and no completion frame is emitted, so the
+ * public stop event stays deferred.
+ *
+ * Install alongside one or more `deferred(...)`-wrapped detector strategies
+ * that drive `on_user_turn_inference_triggered` but leave finalization to
+ * this strategy.
+ */
+export class LLMTurnCompletionUserTurnStopStrategy extends ExternalUserTurnCompletionStopStrategy {
+    _config;
+    constructor(options = {}) {
+        super(options);
+        this._config = options.config ?? new UserTurnCompletionConfig();
+    }
+    /** Return the configured `UserTurnCompletionConfig`. */
+    get config() {
+        return this._config;
+    }
+    /** Configure the LLM on start and delegate completion handling to the base. */
+    async processFrame(frame) {
+        if (frame instanceof StartFrame) {
+            await this._configureLlm();
+        }
+        return await super.processFrame(frame);
+    }
+    async _configureLlm() {
+        await this.pushFrame(new LLMUpdateSettingsFrame({
+            delta: new LLMSettings({
+                filterIncompleteUserTurns: true,
+                userTurnCompletionConfig: this._config,
+            }),
+            reachInactiveServices: true,
+        }));
+    }
+}
+//# sourceMappingURL=llm_turn_completion_user_turn_stop_strategy.js.map

package/dist/turns/user_stop/speech_timeout_user_turn_stop_strategy.d.ts

@@ -0,0 +1,140 @@
+/** Speech timeout-based user turn stop strategy. */
+import { type Task } from "@pipedog/asyncio";
+import { type Frame, TranscriptionFrame, VADUserStartedSpeakingFrame, VADUserStoppedSpeakingFrame } from "../../frames/frames.ts";
+import type { FrameProcessorSetup } from "../../processors/frame_processor.ts";
+import { ProcessFrameResult } from "../types.ts";
+import { BaseUserTurnStopStrategy, type BaseUserTurnStopStrategyOptions } from "./base_user_turn_stop_strategy.ts";
+export interface SpeechTimeoutUserTurnStopStrategyOptions extends BaseUserTurnStopStrategyOptions {
+    /**
+     * Time to wait for the user to potentially say more after they pause
+     * speaking. Defaults to 0.6 seconds.
+     */
+    userSpeechTimeout?: number;
+    /**
+     * Whether to require at least one transcript before triggering end-of-turn.
+     * When true (default), turn-end fires only after the user-speech timer
+     * expires *and* at least one transcript has been received. When false, the
+     * strategy signals turn-end as soon as VAD reports end of speech and the
+     * user-speech timer has elapsed — independent of transcripts. Set this to
+     * false when local turn detection is the intended driver of the
+     * conversation (e.g. with a realtime LLM service consuming audio directly),
+     * so transcripts are off the latency critical path.
+     * `LLMContextAggregatorPair` flips this for you when
+     * `realtimeServiceMode: true`.
+     */
+    waitForTranscript?: boolean;
+}
+/**
+ * User turn stop strategy using two independent timers after VAD stop.
+ *
+ * After the user stops speaking (detected by VAD), this strategy runs two
+ * independent timers. The user turn stop is triggered only when both have
+ * finished and at least one transcript has been received:
+ *
+ * - userSpeechTimeout: Policy floor — the window in which the user may
+ *   resume speaking after a pause. Always runs to completion.
+ * - sttTimeout: Safety net for STT latency — the P99 time for the STT
+ *   service to return a final transcript after VAD stop, adjusted by the
+ *   VAD stopSecs. Short-circuited when the STT service emits a finalized
+ *   transcript (`TranscriptionFrame.finalized`), since finalization means
+ *   STT has nothing more to send.
+ *
+ * Fallback: when a transcript arrives without a VAD stop event, the
+ * userSpeechTimeout timer measures inactivity since the last transcript
+ * (rearmed on each transcript). sttTimeout has no meaning here since it
+ * is defined relative to VAD stop, and STT has already emitted a
+ * transcript — so the stt wait is marked done immediately.
+ */
+export declare class SpeechTimeoutUserTurnStopStrategy extends BaseUserTurnStopStrategy {
+    protected _userSpeechTimeout: number;
+    protected _waitForTranscript: boolean;
+    protected _sttTimeout: number;
+    protected _stopSecs: number;
+    protected _stopSecsWarned: boolean;
+    protected _text: string;
+    protected _vadUserSpeaking: boolean;
+    protected _transcriptFinalized: boolean;
+    protected _vadStopped: boolean;
+    protected _userSpeechTimeoutTask: Task<unknown> | null;
+    protected _sttTimeoutTask: Task<unknown> | null;
+    protected _userSpeechWaitDone: boolean;
+    protected _sttWaitDone: boolean;
+    constructor(options?: SpeechTimeoutUserTurnStopStrategyOptions);
+    /** Whether transcripts gate end-of-turn signalling. */
+    get waitForTranscript(): boolean;
+    set waitForTranscript(value: boolean);
+    /**
+     * Ready the strategy to detect the end of the turn now starting.
+     *
+     * `_vadUserSpeaking` is deliberately preserved: it reflects the live
+     * physical VAD state, not turn-scoped bookkeeping. VAD only re-emits a
+     * start after a stop, so clearing the flag for a turn that begins while
+     * the user is still speaking would leave the strategy with no active VAD
+     * reference, treating any transcript as a standalone utterance.
+     */
+    handleUserTurnStarted(): Promise<void>;
+    /** Clear per-turn state once the turn has ended. */
+    handleUserTurnStopped(): Promise<void>;
+    /** Clear per-turn state, optionally resetting the live VAD flag. */
+    protected _reset(options: {
+        clearVadUserSpeaking: boolean;
+    }): Promise<void>;
+    /**
+     * Drop whatever progress toward an end-of-turn has been made so far.
+     *
+     * Runs at a turn boundary, and whenever VAD reports the user speaking
+     * again — which makes earlier progress stale mid-turn.
+     */
+    protected _discardPendingEndOfTurn(): Promise<void>;
+    /**
+     * Set up the strategy.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /** Cleanup the strategy. */
+    cleanup(): Promise<void>;
+    /**
+     * Process an incoming frame to update strategy state.
+     *
+     * Updates internal transcription text and VAD state. The user end turn
+     * will be triggered when appropriate based on the collected frames.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns Always returns CONTINUE so subsequent stop strategies are evaluated.
+     */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+    /** Handle when the VAD indicates the user is speaking. */
+    protected _handleVadUserStartedSpeaking(_frame: VADUserStartedSpeakingFrame): Promise<void>;
+    /** Handle when the VAD indicates the user has stopped speaking. */
+    protected _handleVadUserStoppedSpeaking(frame: VADUserStoppedSpeakingFrame): Promise<void>;
+    /** Handle user transcription. */
+    protected _handleTranscription(frame: TranscriptionFrame): Promise<void>;
+    /** Cancel any running user-speech timer and start a fresh one. */
+    protected _restartUserSpeechTimer(): Promise<void>;
+    /**
+     * Wait userSpeechTimeout then attempt to trigger user turn stopped.
+     *
+     * @param timeout The timeout in seconds to wait.
+     */
+    protected _userSpeechTimeoutHandler(timeout: number): Promise<void>;
+    /**
+     * Wait sttTimeout then attempt to trigger user turn stopped.
+     *
+     * @param timeout The timeout in seconds to wait.
+     */
+    protected _sttTimeoutHandler(timeout: number): Promise<void>;
+    /**
+     * Trigger user turn stopped if all required conditions are met.
+     *
+     * Both timers must be done (stt is marked done immediately on the
+     * fallback path and when finalization short-circuits the safety net),
+     * the user must not be currently speaking, and — when
+     * `waitForTranscript` is true — at least one transcript must have been
+     * received.
+     */
+    protected _maybeTriggerUserTurnStopped(): Promise<void>;
+    /** Cancel any running timer tasks and clear the handles. */
+    protected _cancelAllTasks(): Promise<void>;
+}
+//# sourceMappingURL=speech_timeout_user_turn_stop_strategy.d.ts.map