@pipedog/core 0.0.0 → 0.2.0

package/dist/utils/context/word_completion_tracker.d.ts

@@ -0,0 +1,273 @@
+import { TextSegmentMap } from "./text_segment_map.ts";
+export interface WordCompletionTrackerOptions {
+    /**
+     * What the LLM wrote, with any delimiters an aggregator split off
+     * (`<card>4111 1111</card>`). Supply it to have each word attributed back
+     * to it via `getLlmConsumed`, which is what keeps those delimiters in the
+     * conversation context.
+     */
+    llmText?: string | null;
+    /**
+     * What a client displays -- no tags, no rewrites. Defaults to `ttsText`
+     * with markup stripped.
+     */
+    userFacingText?: string | null;
+}
+/**
+ * Follows one AggregatedTextFrame from dispatch until it is fully spoken.
+ *
+ * A TTS provider reports the words it speaks one event at a time. This class
+ * consumes those events for a single frame and answers, for each one:
+ *
+ * - What text should the emitted `TTSTextFrame` carry? -- `getWordForFrame`
+ * - Which of the LLM's own text does that stand for? -- `getLlmConsumed`
+ * - How much of the frame has been spoken? -- `getAccumulatedUserFacingText`
+ *   and `getRemainingUserFacingText`
+ * - Is the frame finished? -- the return of `addWordAndCheckComplete`
+ * - Did the word run past this frame? -- `getOverflowWord`
+ *
+ * Three texts describe the same frame, and each answer above is phrased in
+ * one of them:
+ *
+ * | Text             | Example                      | Answers about           |
+ * |------------------|------------------------------|-------------------------|
+ * | `ttsText`        | `<spell>4111 1111</spell>`   | what was spoken         |
+ * | `userFacingText` | `4111 1111`                  | what a UI displays      |
+ * | `llmText`        | `<card>4111 1111</card>`     | what the context stores |
+ *
+ * Keeping a position in all three is the job of `TextSegmentMap`, which this
+ * class owns one of and defers to for every question of *where*. What the
+ * tracker adds is the handful of decisions a position alone cannot express:
+ *
+ * - **Providers drop events.** A word the provider never reported has no
+ *   event coming, so the next word that does arrive is matched a little
+ *   further on and the text passed over is emitted with it. When nothing
+ *   matches at all, waiting would stall this frame and everything queued
+ *   behind it, so the frame is force-completed instead: the unspoken remainder
+ *   is emitted so the context still gets it, and the stray word is handed
+ *   back for the next frame to try.
+ * - **Some text is never spoken.** A closing `</card>`, or a tag sitting
+ *   between the last word and its punctuation, never arrives as its own
+ *   event. Whatever is left once everything speakable is done belongs to this
+ *   frame, so the word that finishes it claims the rest.
+ * - **A word can belong to two frames.** A provider may merge across the
+ *   boundary (`"1111And"`). The part that fits stays here; the rest is
+ *   exposed as overflow for the caller to feed to the next frame.
+ *
+ * @example
+ * const tracker = new WordCompletionTracker("Hello, world!");
+ * tracker.addWordAndCheckComplete("Hello"); // false
+ * tracker.addWordAndCheckComplete("world"); // true -- nothing left to speak
+ */
+export declare class WordCompletionTracker {
+    protected _ttsText: string;
+    protected _userFacingText: string;
+    protected _llmText: string | null;
+    protected _userFacingPos: number;
+    protected _llmPos: number;
+    protected _llmSpokenPos: number;
+    protected _frameWord: string | null;
+    protected _overflowWord: string | null;
+    protected _llmConsumed: string | null;
+    protected _forceCompleted: boolean;
+    protected _segmentMap: TextSegmentMap;
+    /**
+     * Initialize the tracker with the frame's three texts.
+     *
+     * Only `ttsText` is required; the other two default to it, which is exactly
+     * right for a frame nothing rewrote.
+     *
+     * @param ttsText What was sent to the TTS, and so what the incoming words
+     *   are matched against. May carry synthesis tags (`<spell>...`).
+     * @param options.llmText What the LLM wrote (see `WordCompletionTrackerOptions`).
+     * @param options.userFacingText What a client displays.
+     */
+    constructor(ttsText: string, options?: WordCompletionTrackerOptions);
+    /**
+     * Record one word the TTS provider reported speaking.
+     *
+     * Three things can happen, in this order:
+     *
+     * 1. The frame is already finished -- the word is ignored.
+     * 2. The word does not match what is left to speak, so the provider must
+     *    have dropped an event: the frame is force-completed (see
+     *    `_forceComplete`) and this word is handed back as overflow.
+     * 3. Otherwise the word advances the frame. Afterwards the `get*` accessors
+     *    describe it: this frame's share of the word, the LLM text it stands
+     *    for, and how much of the frame is now spoken.
+     *
+     * @param word One token from the provider's word-timestamp stream. It may
+     *   be a plain word, a word carrying its own spacing or punctuation, or a
+     *   fragment of a still-open SSML tag -- matching is textual, so none of
+     *   those need special handling from the caller. Services that report
+     *   spaces and punctuation as separate tokens (e.g. Inworld) must merge
+     *   them into the preceding word first, via `mergePunctTokens`.
+     * @returns True once nothing is left for this frame to speak.
+     */
+    addWordAndCheckComplete(word: string): boolean;
+    /**
+     * End this frame early because `word` does not belong to it.
+     *
+     * The provider dropped one or more events, so the rest of this frame will
+     * never be reported. Rather than stall, emit the unspoken remainder as this
+     * frame's word -- the conversation context still receives the full text --
+     * and hand `word` back as overflow for the next frame to try.
+     *
+     * The segment map is deliberately left where it is, since nothing here was
+     * actually spoken; `_forceCompleted` answers for it from now on.
+     *
+     * @returns Always true -- the frame is finished.
+     */
+    protected _forceComplete(word: string): boolean;
+    /**
+     * Move the cursors to the end, for a caller that emits the remainder itself.
+     *
+     * The accumulated and remaining views then agree with the text that went out.
+     */
+    takeRemainingAsSpoken(): void;
+    /**
+     * Record which part of `llmText` the word just added stands for.
+     *
+     * Usually that is simply the span the attributed cursor moved over. Two
+     * cases reach further, and both leave `_llmPos` ahead of the map's:
+     *
+     * - **The word finished the frame**: take everything to the end of
+     *   `llmText`. The map stops at the last spoken character, so a closing tag
+     *   -- which never arrives as its own event -- is still outstanding and
+     *   belongs to this word.
+     * - **Neither cursor moved**: the map accepted the word without matching it
+     *   to anything, as it does for a symbol the source text spells differently
+     *   (a provider reporting `->` for `→`). Nothing else will ever report that
+     *   character, so the word's own length is spent on it instead.
+     *
+     * A word inside a transformed segment records nothing, and is checked
+     * before that second case: the cursors are held there on purpose, so "did
+     * not move" would be misread as "stood for something unmatched" and would
+     * walk through text the transform covers. Only the word completing the
+     * segment carries its original span.
+     *
+     * An empty span is not the same as an unmatched word -- it means an earlier
+     * word already covered this one, which `suppressInContext` reports so the
+     * context does not record it twice.
+     */
+    protected _recordLlmSpan(word: string, llmPosBefore: number, spokenBefore: number): void;
+    /**
+     * Return true if `word` plausibly continues what this frame has left to say.
+     *
+     * A false answer means the provider dropped an event. Callers ask this
+     * before adding a word so they can offer it to the next frame instead;
+     * adding it anyway force-completes this one.
+     */
+    wordBelongsHere(word: string): boolean;
+    /**
+     * True when the last word must not be written to the conversation context.
+     *
+     * Two kinds of word answer to this, both of which the context already has
+     * covered, or will have:
+     *
+     * - **One step inside a rewritten span.** `"$42.50"` is spoken as five
+     *   words, none of which the transcript should contain; the word that
+     *   finishes the span carries `"$42.50"` for all of them.
+     * - **A word with no span of its own.** A provider reporting `","` on its
+     *   own, after `"Yeah"` took the comma into its span, has nothing left to
+     *   record. The context falls back to the spoken text when a word carries
+     *   no span, which would store the mark a second time.
+     *
+     * The word is still emitted either way: the provider spoke it, and a
+     * consumer reading the word stream should see it. Without an `llmText`
+     * there are no spans at all, so nothing is suppressed and every word is
+     * recorded from its spoken text as usual.
+     */
+    suppressInContext(): boolean;
+    /**
+     * Return this frame's share of the last word -- the text to emit for it.
+     *
+     * Usually the whole word. A word straddling the boundary gives up its tail
+     * (`"1111"` out of `"1111And"`), and a word that repeats the previous word's
+     * punctuation gives up that mark. A word matched past an event the provider
+     * never sent brings along the text it passed over, and after a
+     * force-complete this is the frame's unspoken remainder instead -- either
+     * way, nothing is missing from the turn.
+     */
+    getWordForFrame(): string | null;
+    /**
+     * Return the part of the last word that belongs to the *next* frame.
+     *
+     * Feed it to that frame's tracker as if the provider had sent it there.
+     * Casing and punctuation are untouched so it still reads as a real word.
+     * `null` when the word fit entirely within this frame.
+     */
+    getOverflowWord(): string | null;
+    /**
+     * Return the LLM's own text that the last word stands for.
+     *
+     * This is what the conversation context records, so it keeps the tags and
+     * spellings the LLM wrote (`"<card>4111"`) rather than what the provider
+     * reported speaking (`"4111"`).
+     *
+     * `null` when there is nothing to attribute: no `llmText` was given, the
+     * word is mid-rewrite, or `llmText` is already exhausted (a trailing emoji
+     * it never carried).
+     */
+    getLlmConsumed(): string | null;
+    /**
+     * Return the part of the frame spoken so far, as the user sees it.
+     *
+     * With `getRemainingUserFacingText` this splits the frame's text in two,
+     * which is what lets a client highlight speech as it happens.
+     */
+    getAccumulatedUserFacingText(): string;
+    /**
+     * Return the part of the frame not yet spoken, as the user sees it.
+     *
+     * @param strip Whether to trim surrounding whitespace. Pass false to keep
+     *   the leading space, so accumulated + remaining reproduces the frame's
+     *   text exactly -- callers that index into that text rely on it.
+     */
+    getRemainingUserFacingText(strip?: boolean): string;
+    /**
+     * Return everything spoken so far, as it was sent to the TTS.
+     *
+     * The whole frame up to the cursor, where `getWordForFrame` describes only
+     * the most recent word.
+     */
+    getAccumulatedTtsText(): string;
+    /**
+     * Return everything spoken so far, as the LLM wrote it.
+     *
+     * The whole frame up to the cursor, where `getLlmConsumed` describes only
+     * the most recent word. `null` without an `llmText`.
+     */
+    getAccumulatedLlmText(): string | null;
+    /**
+     * Return what this frame still has left to speak.
+     *
+     * Callers ending a frame early emit this, so text the provider never
+     * reported still reaches the conversation context.
+     *
+     * @param strip Whether to trim surrounding whitespace. Pass false to keep
+     *   the leading space, so accumulated + remaining reproduces `ttsText`
+     *   exactly.
+     */
+    getRemainingTtsText(strip?: boolean): string;
+    /**
+     * Return what this frame still has left to speak, as the LLM wrote it.
+     *
+     * The companion to `getRemainingTtsText` when ending a frame early: that
+     * supplies the text to emit, this the text to record. `null` without an
+     * `llmText`, or when nothing is left.
+     */
+    getRemainingLlmText(): string | null;
+    /**
+     * True when this frame has nothing left to speak.
+     *
+     * Alphanumeric content is what counts, so a frame whose remainder is only
+     * punctuation or a closing tag is already finished -- no word will ever
+     * arrive for those.
+     */
+    get isComplete(): boolean;
+    /** Rewind to the start of the frame, keeping the three texts. */
+    reset(): void;
+    toString(): string;
+}
+//# sourceMappingURL=word_completion_tracker.d.ts.map