@pipedog/core 0.0.0 → 0.1.0

package/dist/turns/user_stop/deferred_user_turn_stop_strategy.js

@@ -0,0 +1,107 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_stop/deferred_user_turn_stop_strategy.py
+import { BaseUserTurnStopStrategy, } from "./base_user_turn_stop_strategy.js";
+/**
+ * Wraps a stop strategy and suppresses its `on_user_turn_stopped` event.
+ *
+ * Event subscriptions added to the wrapper are forwarded directly to
+ * the inner strategy, except for `on_user_turn_stopped`, which is
+ * dropped. The inner strategy's frame-side and inference-triggered
+ * events therefore reach external listeners (the controller, etc.)
+ * unchanged; finalization is left to another strategy in the chain
+ * such as `LLMTurnCompletionUserTurnStopStrategy`.
+ *
+ * Use the `deferred` helper for ergonomic construction:
+ *
+ * @example
+ * stop: [
+ *   deferred(new TurnAnalyzerUserTurnStopStrategy({ turnAnalyzer })),
+ *   new LLMTurnCompletionUserTurnStopStrategy(),
+ * ]
+ */
+export class DeferredUserTurnStopStrategy extends BaseUserTurnStopStrategy {
+    _inner;
+    /**
+     * @param inner The strategy whose finalization should be deferred.
+     * @param options Additional options forwarded to the base class.
+     */
+    constructor(inner, options = {}) {
+        super(options);
+        this._inner = inner;
+    }
+    /** Return the wrapped strategy. */
+    get inner() {
+        return this._inner;
+    }
+    /**
+     * Report what the inner strategy does with proposals.
+     *
+     * Frame processing is forwarded, so a proposal reaches the inner strategy
+     * and is resolved there. Deferring finalization changes when the turn ends,
+     * not who decides it.
+     */
+    get resolvesProposedTurnStopFrames() {
+        return this._inner.resolvesProposedTurnStopFrames;
+    }
+    /**
+     * Forward event subscriptions to the inner strategy.
+     *
+     * `on_user_turn_stopped` is silently dropped — that's the whole point of
+     * the wrapper. Every other event handler is attached to the inner strategy
+     * directly, so the inner's events reach the listener without any per-event
+     * proxy method on the wrapper.
+     */
+    addEventHandler(eventName, handler) {
+        if (eventName === "on_user_turn_stopped") {
+            return;
+        }
+        this._inner.addEventHandler(eventName, handler);
+    }
+    /** Set up the inner strategy. */
+    async setup(setup) {
+        await super.setup(setup);
+        await this._inner.setup(setup);
+    }
+    /** Clean up the inner strategy. */
+    async cleanup() {
+        await super.cleanup();
+        await this._inner.cleanup();
+    }
+    /** Forward the turn-started callback to the inner strategy. */
+    async handleUserTurnStarted() {
+        await this._inner.handleUserTurnStarted();
+    }
+    /** Forward the turn-stopped callback to the inner strategy. */
+    async handleUserTurnStopped() {
+        await this._inner.handleUserTurnStopped();
+    }
+    /** Forward frame processing to the inner strategy. */
+    async processFrame(frame) {
+        return await this._inner.processFrame(frame);
+    }
+}
+/**
+ * Defer this stop strategy's finalization to another strategy.
+ *
+ * Wraps `strategy` in a `DeferredUserTurnStopStrategy`: the inner strategy
+ * continues to drive inference-triggered events, but its
+ * `on_user_turn_stopped` event is suppressed. Use when another strategy in
+ * the chain (e.g. `LLMTurnCompletionUserTurnStopStrategy`) owns finalization.
+ *
+ * @example
+ * stop: [
+ *   deferred(new TurnAnalyzerUserTurnStopStrategy({ turnAnalyzer })),
+ *   new LLMTurnCompletionUserTurnStopStrategy(),
+ * ]
+ *
+ * @param strategy The stop strategy to defer.
+ * @returns A wrapper that exposes the inner strategy's behavior with
+ *   finalization suppressed.
+ */
+export function deferred(strategy) {
+    return new DeferredUserTurnStopStrategy(strategy);
+}
+//# sourceMappingURL=deferred_user_turn_stop_strategy.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Decides whether a speculative response is still the right answer.
+ *
+ * A speculative response is generated from an eager transcript, before the
+ * service commits one. This decides whether the committed transcript is close
+ * enough to the eager one for that response to stand.
+ */
+export declare abstract class EagerMatchPolicy {
+    /**
+     * Report whether the committed transcript still matches the eager one.
+     *
+     * @param eager The transcript the speculative response was generated from.
+     * @param final The transcript the service committed to.
+     * @returns True to keep the speculative response, false to discard it and
+     *   answer the committed transcript instead.
+     */
+    abstract matches(eager: string, final: string): boolean;
+}
+/** Keep the response only when the two transcripts are identical. */
+export declare class ExactMatch extends EagerMatchPolicy {
+    /** Report whether the two transcripts are identical. */
+    matches(eager: string, final: string): boolean;
+}
+/**
+ * Keep the response when the transcripts differ only in formatting.
+ *
+ * Compares with case, punctuation and whitespace removed. Services commonly
+ * format the committed transcript — capitalizing it, punctuating it — while
+ * leaving the eager one raw, which `ExactMatch` counts as a difference.
+ */
+export declare class NormalizedMatch extends EagerMatchPolicy {
+    /** Report whether the two transcripts match once formatting is removed. */
+    matches(eager: string, final: string): boolean;
+    protected static _normalize(text: string): string;
+}
+//# sourceMappingURL=eager_match_policy.d.ts.map

package/dist/turns/user_stop/eager_match_policy.js

@@ -0,0 +1,50 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_stop/eager_match_policy.py
+/** Policies deciding whether an eager transcript still matches the committed one. */
+// Apostrophes are dropped rather than spaced out, so a service that writes
+// "it's" matches one that writes "its".
+const APOSTROPHES = /['’ʼ]/gu;
+// Python's `[^\w\s]` with re.UNICODE.
+const PUNCTUATION = /[^\p{L}\p{N}\p{M}_\s]/gu;
+const WHITESPACE = /\s+/gu;
+/**
+ * Decides whether a speculative response is still the right answer.
+ *
+ * A speculative response is generated from an eager transcript, before the
+ * service commits one. This decides whether the committed transcript is close
+ * enough to the eager one for that response to stand.
+ */
+export class EagerMatchPolicy {
+}
+/** Keep the response only when the two transcripts are identical. */
+export class ExactMatch extends EagerMatchPolicy {
+    /** Report whether the two transcripts are identical. */
+    matches(eager, final) {
+        return eager === final;
+    }
+}
+/**
+ * Keep the response when the transcripts differ only in formatting.
+ *
+ * Compares with case, punctuation and whitespace removed. Services commonly
+ * format the committed transcript — capitalizing it, punctuating it — while
+ * leaving the eager one raw, which `ExactMatch` counts as a difference.
+ */
+export class NormalizedMatch extends EagerMatchPolicy {
+    /** Report whether the two transcripts match once formatting is removed. */
+    matches(eager, final) {
+        return NormalizedMatch._normalize(eager) === NormalizedMatch._normalize(final);
+    }
+    static _normalize(text) {
+        // NFKC + full case folding (Python's casefold); toLowerCase after an
+        // uppercase pass approximates folding for the common special cases (ß).
+        let normalized = text.normalize("NFKC").toUpperCase().toLowerCase();
+        normalized = normalized.replace(APOSTROPHES, "");
+        normalized = normalized.replace(PUNCTUATION, " ");
+        return normalized.replace(WHITESPACE, " ").trim();
+    }
+}
+//# sourceMappingURL=eager_match_policy.js.map

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

@@ -0,0 +1,84 @@
+/** User turn stop strategy that answers an eager end of turn speculatively. */
+import { type Task } from "@pipedog/asyncio";
+import { EagerTranscriptionFrame, type Frame } from "../../frames/frames.ts";
+import { type ProcessFrameResult, UserTurnSpeculation } from "../types.ts";
+import type { TriggerUserTurnStoppedOptions } from "./base_user_turn_stop_strategy.ts";
+import { type EagerMatchPolicy } from "./eager_match_policy.ts";
+import { ExternalUserTurnStopStrategy, type ExternalUserTurnStopStrategyOptions } from "./external_user_turn_stop_strategy.ts";
+export interface EagerUserTurnStopStrategyOptions extends ExternalUserTurnStopStrategyOptions {
+    /**
+     * Decides whether the committed transcript is close enough to the eager one
+     * to keep the speculative response. Defaults to `NormalizedMatch`, which
+     * ignores the capitalization and punctuation services commonly add when
+     * they commit a transcript. Pass `ExactMatch` to require the two to be
+     * identical.
+     */
+    matchPolicy?: EagerMatchPolicy | null;
+    /**
+     * Seconds a prediction may go unresolved before it is withdrawn. A service
+     * that stops sending turn signals mid-speculation would otherwise leave the
+     * response held and the bot silent for the rest of the session.
+     */
+    speculationTimeout?: number;
+}
+/**
+ * Answers an eager end of turn while the turn is still open.
+ *
+ * Some STT services predict the end of a turn before committing to it, and
+ * withdraw the prediction if the user turns out to be mid-sentence. This
+ * strategy starts generating a response on that prediction, so the gap between
+ * it and the committed end of turn is spent generating rather than waiting.
+ *
+ * The prediction can be wrong in three ways, and each withdraws the response:
+ *
+ * - the user resumes speaking, and the service withdraws the eager end of turn
+ * - the committed transcript differs from the eager one, per `matchPolicy`
+ * - the turn never commits within `speculationTimeout`
+ *
+ * Every one of those leaves as an `EagerEndOfTurnCancelFrame` from here, so a
+ * response is never dropped somewhere the rest of the pipeline cannot see.
+ *
+ * Nothing the speculation produces reaches the user or the context. The
+ * inference runs against a provisional context, and its response is held by
+ * the LLM service's `SpeculationGate` until the turn is confirmed. The turn
+ * ends normally: the user message written to the context is always the
+ * committed transcript, never the eager one.
+ *
+ * Install it with `EagerUserTurnStrategies` rather than directly — the
+ * service owns turn detection here, so it replaces the detector chain instead
+ * of running alongside it.
+ */
+export declare class EagerUserTurnStopStrategy extends ExternalUserTurnStopStrategy {
+    protected _matchPolicy: EagerMatchPolicy;
+    protected _speculationTimeout: number;
+    protected _speculationTimeoutTask: Task<unknown> | null;
+    protected _speculation: UserTurnSpeculation | null;
+    constructor(options?: EagerUserTurnStopStrategyOptions);
+    /** The policy deciding whether a speculative response still applies. */
+    get matchPolicy(): EagerMatchPolicy;
+    /**
+     * Start a speculation on an eager end of turn, or withdraw one.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns Always CONTINUE, so subsequent stop strategies are evaluated.
+     */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+    /** End the turn, keeping the speculative response only if it still applies. */
+    triggerUserTurnStopped(options?: TriggerUserTurnStoppedOptions): Promise<void>;
+    /** Clear per-turn state. Runs at both turn boundaries. */
+    protected _reset(): Promise<void>;
+    /** Answer an eager end of turn, leaving the turn open. */
+    protected _speculate(frame: EagerTranscriptionFrame): Promise<void>;
+    /** Withdraw a prediction the turn never resolved. */
+    protected _speculationTimeoutHandler(speculation: UserTurnSpeculation): Promise<void>;
+    /**
+     * Take the speculation in flight, stopping the clock on it.
+     *
+     * The single exit, so a resolved speculation can never be withdrawn again
+     * by a timer still running for it.
+     */
+    protected _takeSpeculation(): Promise<UserTurnSpeculation | null>;
+    /** Drop a speculation the service withdrew. */
+    protected _forget(): Promise<void>;
+}
+//# sourceMappingURL=eager_user_turn_stop_strategy.d.ts.map

package/dist/turns/user_stop/eager_user_turn_stop_strategy.js

@@ -0,0 +1,154 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_stop/eager_user_turn_stop_strategy.py
+/** User turn stop strategy that answers an eager end of turn speculatively. */
+import { sleep } from "@pipedog/asyncio";
+import { EagerEndOfTurnCancelFrame, EagerTranscriptionFrame, } from "../../frames/frames.js";
+import { logger } from "../../utils/logger.js";
+import { UserTurnSpeculation } from "../types.js";
+import { NormalizedMatch } from "./eager_match_policy.js";
+import { ExternalUserTurnStopStrategy, } from "./external_user_turn_stop_strategy.js";
+/**
+ * Answers an eager end of turn while the turn is still open.
+ *
+ * Some STT services predict the end of a turn before committing to it, and
+ * withdraw the prediction if the user turns out to be mid-sentence. This
+ * strategy starts generating a response on that prediction, so the gap between
+ * it and the committed end of turn is spent generating rather than waiting.
+ *
+ * The prediction can be wrong in three ways, and each withdraws the response:
+ *
+ * - the user resumes speaking, and the service withdraws the eager end of turn
+ * - the committed transcript differs from the eager one, per `matchPolicy`
+ * - the turn never commits within `speculationTimeout`
+ *
+ * Every one of those leaves as an `EagerEndOfTurnCancelFrame` from here, so a
+ * response is never dropped somewhere the rest of the pipeline cannot see.
+ *
+ * Nothing the speculation produces reaches the user or the context. The
+ * inference runs against a provisional context, and its response is held by
+ * the LLM service's `SpeculationGate` until the turn is confirmed. The turn
+ * ends normally: the user message written to the context is always the
+ * committed transcript, never the eager one.
+ *
+ * Install it with `EagerUserTurnStrategies` rather than directly — the
+ * service owns turn detection here, so it replaces the detector chain instead
+ * of running alongside it.
+ */
+export class EagerUserTurnStopStrategy extends ExternalUserTurnStopStrategy {
+    _matchPolicy;
+    _speculationTimeout;
+    _speculationTimeoutTask = null;
+    _speculation = null;
+    constructor(options = {}) {
+        super(options);
+        this._matchPolicy = options.matchPolicy ?? new NormalizedMatch();
+        this._speculationTimeout = options.speculationTimeout ?? 5.0;
+    }
+    /** The policy deciding whether a speculative response still applies. */
+    get matchPolicy() {
+        return this._matchPolicy;
+    }
+    /**
+     * Start a speculation on an eager end of turn, or withdraw one.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns Always CONTINUE, so subsequent stop strategies are evaluated.
+     */
+    async processFrame(frame) {
+        if (frame instanceof EagerTranscriptionFrame) {
+            await this._speculate(frame);
+        }
+        else if (frame instanceof EagerEndOfTurnCancelFrame) {
+            // The service withdrew its prediction, and its frame reaches every
+            // consumer on its own. Only our own state is left to clear.
+            await this._forget();
+        }
+        return await super.processFrame(frame);
+    }
+    /** End the turn, keeping the speculative response only if it still applies. */
+    async triggerUserTurnStopped(options = {}) {
+        const enableUserSpeakingFrames = options.enableUserSpeakingFrames ?? null;
+        const speculation = await this._takeSpeculation();
+        if (!speculation) {
+            await super.triggerUserTurnStopped({ enableUserSpeakingFrames });
+            return;
+        }
+        if (this._matchPolicy.matches(speculation.text, this._text)) {
+            logger.debug(`${this}: eager end of turn held, keeping the speculative response`);
+            // Inference already ran, on the eager transcript. Only finalize:
+            // the UserStoppedSpeakingFrame it emits is what releases the
+            // response, and the flag stops a second inference answering the
+            // same turn.
+            await this.triggerUserTurnFinalized({
+                enableUserSpeakingFrames,
+                confirmsSpeculation: true,
+            });
+            return;
+        }
+        logger.debug(`${this}: eager end of turn missed, discarding the speculative response ` +
+            `(eager: [${speculation.text}], committed: [${this._text}])`);
+        await this.triggerUserTurnSpeculationCancelled();
+        // Inference has to run again, on the committed transcript, so fire both
+        // events rather than just finalizing.
+        await super.triggerUserTurnStopped({ enableUserSpeakingFrames });
+    }
+    /** Clear per-turn state. Runs at both turn boundaries. */
+    async _reset() {
+        const speculation = await this._takeSpeculation();
+        await super._reset();
+        if (speculation) {
+            // The turn ended without resolving the speculation — the stop
+            // watchdog, an interruption, session end. Nothing else will withdraw
+            // it, so the response would be held until the gate times out.
+            logger.debug(`${this}: turn ended unresolved, discarding the speculative response`);
+            await this.triggerUserTurnSpeculationCancelled();
+        }
+    }
+    /** Answer an eager end of turn, leaving the turn open. */
+    async _speculate(frame) {
+        // Segments committed earlier in this turn are part of what the LLM will
+        // see, so they're part of what the committed transcript is compared to.
+        const speculation = new UserTurnSpeculation({ text: this._text + frame.text });
+        this._speculation = speculation;
+        this._speculationTimeoutTask = this.taskManager.createTask(() => this._speculationTimeoutHandler(speculation), `${this}::_speculation_timeout_handler`);
+        logger.debug(`${this}: speculating on eager end of turn: [${speculation.text}]`);
+        await this.triggerUserTurnInferenceTriggered({ speculation });
+    }
+    /** Withdraw a prediction the turn never resolved. */
+    async _speculationTimeoutHandler(speculation) {
+        await sleep(this._speculationTimeout);
+        // Cleared here rather than by a cancellation, since this timer fired.
+        this._speculationTimeoutTask = null;
+        if (this._speculation !== speculation) {
+            return;
+        }
+        logger.debug(`${this}: eager end of turn unresolved after ${this._speculationTimeout}s, ` +
+            "discarding the speculative response");
+        this._speculation = null;
+        await this.triggerUserTurnSpeculationCancelled();
+    }
+    /**
+     * Take the speculation in flight, stopping the clock on it.
+     *
+     * The single exit, so a resolved speculation can never be withdrawn again
+     * by a timer still running for it.
+     */
+    async _takeSpeculation() {
+        const speculation = this._speculation;
+        this._speculation = null;
+        if (this._speculationTimeoutTask) {
+            const task = this._speculationTimeoutTask;
+            this._speculationTimeoutTask = null;
+            await this.cancelTask(task);
+        }
+        return speculation;
+    }
+    /** Drop a speculation the service withdrew. */
+    async _forget() {
+        await this._takeSpeculation();
+    }
+}
+//# sourceMappingURL=eager_user_turn_stop_strategy.js.map

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

@@ -0,0 +1,45 @@
+/** User turn stop strategy that finalizes on `UserTurnInferenceCompletedFrame`. */
+import { type Frame } from "../../frames/frames.ts";
+import { ProcessFrameResult } from "../types.ts";
+import { BaseUserTurnStopStrategy } from "./base_user_turn_stop_strategy.ts";
+/**
+ * Finalize the user turn whenever a `UserTurnInferenceCompletedFrame` arrives.
+ *
+ * Generic stop strategy for pipelines where some external component
+ * (LLM with completion markers, STT with built-in turn detection, a
+ * dedicated end-of-turn classifier, custom user code, etc.) judges
+ * when a turn is semantically complete and emits
+ * `UserTurnInferenceCompletedFrame`.
+ *
+ * Pair this with one or more `deferred(...)`-wrapped detector
+ * strategies that drive `on_user_turn_inference_triggered` but
+ * leave finalization to this strategy:
+ *
+ * @example
+ * stop: [
+ *   deferred(new TurnAnalyzerUserTurnStopStrategy({ turnAnalyzer })),
+ *   new ExternalUserTurnCompletionStopStrategy(),
+ * ]
+ *
+ * For LLM-completion-marker gating specifically, use the subclass
+ * `LLMTurnCompletionUserTurnStopStrategy` instead, which additionally pushes
+ * the `LLMUpdateSettingsFrame` that enables the marker protocol on the LLM.
+ *
+ * A completion resolves with some latency (e.g. the LLM `●` arrives
+ * after the inference finishes), so the user may have resumed speaking
+ * in the meantime. The controller drops a finalization that arrives
+ * while the user is speaking, so a stale completion does not end the
+ * turn (and talk over the user); the turn stays open for the next
+ * inference to re-evaluate. That check lives in the controller, which
+ * holds the authoritative user-speaking state.
+ *
+ * If the producer never emits `UserTurnInferenceCompletedFrame`, the
+ * controller's `userTurnStopTimeout` watchdog finalizes the turn after no
+ * activity. Tune that timeout if your producer can take longer than the
+ * default to respond.
+ */
+export declare class ExternalUserTurnCompletionStopStrategy extends BaseUserTurnStopStrategy {
+    /** Fire `on_user_turn_stopped` whenever `UserTurnInferenceCompletedFrame` is seen. */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+}
+//# sourceMappingURL=external_user_turn_completion_stop_strategy.d.ts.map

package/dist/turns/user_stop/external_user_turn_completion_stop_strategy.js

@@ -0,0 +1,55 @@
+// 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_completion_stop_strategy.py
+/** User turn stop strategy that finalizes on `UserTurnInferenceCompletedFrame`. */
+import { UserTurnInferenceCompletedFrame } from "../../frames/frames.js";
+import { ProcessFrameResult } from "../types.js";
+import { BaseUserTurnStopStrategy } from "./base_user_turn_stop_strategy.js";
+/**
+ * Finalize the user turn whenever a `UserTurnInferenceCompletedFrame` arrives.
+ *
+ * Generic stop strategy for pipelines where some external component
+ * (LLM with completion markers, STT with built-in turn detection, a
+ * dedicated end-of-turn classifier, custom user code, etc.) judges
+ * when a turn is semantically complete and emits
+ * `UserTurnInferenceCompletedFrame`.
+ *
+ * Pair this with one or more `deferred(...)`-wrapped detector
+ * strategies that drive `on_user_turn_inference_triggered` but
+ * leave finalization to this strategy:
+ *
+ * @example
+ * stop: [
+ *   deferred(new TurnAnalyzerUserTurnStopStrategy({ turnAnalyzer })),
+ *   new ExternalUserTurnCompletionStopStrategy(),
+ * ]
+ *
+ * For LLM-completion-marker gating specifically, use the subclass
+ * `LLMTurnCompletionUserTurnStopStrategy` instead, which additionally pushes
+ * the `LLMUpdateSettingsFrame` that enables the marker protocol on the LLM.
+ *
+ * A completion resolves with some latency (e.g. the LLM `●` arrives
+ * after the inference finishes), so the user may have resumed speaking
+ * in the meantime. The controller drops a finalization that arrives
+ * while the user is speaking, so a stale completion does not end the
+ * turn (and talk over the user); the turn stays open for the next
+ * inference to re-evaluate. That check lives in the controller, which
+ * holds the authoritative user-speaking state.
+ *
+ * If the producer never emits `UserTurnInferenceCompletedFrame`, the
+ * controller's `userTurnStopTimeout` watchdog finalizes the turn after no
+ * activity. Tune that timeout if your producer can take longer than the
+ * default to respond.
+ */
+export class ExternalUserTurnCompletionStopStrategy extends BaseUserTurnStopStrategy {
+    /** Fire `on_user_turn_stopped` whenever `UserTurnInferenceCompletedFrame` is seen. */
+    async processFrame(frame) {
+        if (frame instanceof UserTurnInferenceCompletedFrame) {
+            await this.triggerUserTurnFinalized();
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+}
+//# sourceMappingURL=external_user_turn_completion_stop_strategy.js.map

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

@@ -0,0 +1,115 @@
+/** User turn stop strategy driven by another component in the pipeline. */
+import { Event, type Task } from "@pipedog/asyncio";
+import { type Frame, InterimTranscriptionFrame, TranscriptionFrame } 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 ExternalUserTurnStopStrategyOptions extends BaseUserTurnStopStrategyOptions {
+    /**
+     * A short delay (seconds) used internally to handle consecutive or slightly
+     * delayed transcriptions.
+     */
+    timeout?: number;
+    /**
+     * When true (default), turn-stop signaling waits for transcript text to
+     * arrive after the external stop signal. When false, the strategy signals
+     * turn-stop as soon as that signal arrives — 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 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 declare class ExternalUserTurnStopStrategy extends BaseUserTurnStopStrategy {
+    protected _timeout: number;
+    protected _waitForTranscript: boolean;
+    protected _text: string;
+    protected _userSpeaking: boolean;
+    protected _seenInterimResults: boolean;
+    protected _turnAnnouncedElsewhere: boolean;
+    protected _turnOpen: boolean;
+    protected _event: Event;
+    protected _task: Task<unknown> | null;
+    constructor(options?: ExternalUserTurnStopStrategyOptions);
+    /** Whether this strategy resolves proposals into turn stops. */
+    get resolvesProposedTurnStopFrames(): boolean;
+    /** Whether turn-stop signaling waits for transcript text. */
+    get waitForTranscript(): boolean;
+    set waitForTranscript(value: boolean);
+    /** Ready the strategy to detect the end of the turn now starting. */
+    handleUserTurnStarted(): Promise<void>;
+    /** Clear per-turn state once the turn has ended. */
+    handleUserTurnStopped(): Promise<void>;
+    /** Clear per-turn state. Runs at both turn boundaries. */
+    protected _reset(): 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 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.
+     */
+    processFrame(frame: Frame): Promise<ProcessFrameResult>;
+    /** Handle the external signal that the user is speaking. */
+    protected _handleUserStartedSpeaking(options: {
+        announcedElsewhere: boolean;
+    }): Promise<void>;
+    /** Handle the external signal that the user has stopped speaking. */
+    protected _handleUserStoppedSpeaking(options: {
+        announcedElsewhere: boolean;
+    }): Promise<void>;
+    protected _handleInterimTranscription(_frame: InterimTranscriptionFrame): Promise<void>;
+    /** Handle user transcription. */
+    protected _handleTranscription(frame: TranscriptionFrame): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _taskHandler(): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _triggerUserTurnStopped(): Promise<void>;
+    protected _maybeTriggerUserTurnStopped(): Promise<void>;
+}
+//# sourceMappingURL=external_user_turn_stop_strategy.d.ts.map