speechready 0.2.0 → 0.3.0

package/README.md

@@ -57,7 +57,7 @@ for (const token of llmStream) {
 for (const sentence of seg.flush()) speak(sentence);
 ```
 
-For LiveKit Agents (Node), the same thing as a `ttsTextTransforms` entry; sentences are released as they are confirmed, and a fenced code block is handled as one piece:
+For LiveKit Agents (Node), the same thing as a `ttsTextTransforms` entry. It returns the `(ReadableStream<string>) => ReadableStream<string>` the SDK chains; sentences are released as they are confirmed, and a fenced code block is handled as one piece. A complete agent is in [`examples/livekit_agent.mjs`](../examples/livekit_agent.mjs).
 
 ```js
 import { textTransform } from "speechready/livekit";
@@ -88,6 +88,15 @@ lex.toGoogleJson();   // Google Cloud TTS custom pronunciations
 await Lexicon.load("lexicon.json");   // Node only; .yaml files need the optional `yaml` package
 ```
 
+One lexicon is bundled: `tr-tech`, foreign tech acronyms and names as Turkish developers say them (`API` → ey pi ay, `JSON` → ceyson). In Turkish an apostrophe suffix is refitted to the spoken form, so `API'yi` becomes `ey pi ay'ı`.
+
+```js
+import { loadLexicon, prepare } from "speechready";
+
+prepare("API'yi JSON ile çağır.", { locale: "tr-TR", lexicon: "tr-tech" }).text;   // "ey pi ay'ı ceyson ile çağır."
+const lex = loadLexicon("tr-tech");   // a Lexicon you can extend before passing it
+```
+
 ## Differences from the Python package
 
 The two packages produce the same text for every fixture in `spec/fixtures`. The API differs only where the languages do: keyword arguments are one options object, methods are camelCase (`limitFor`, `toPls`, `splitSentences`), `Lexicon.load` is async, and `prepare` takes a `Lexicon` or an entries array rather than a file path.

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { DEFAULT_OPTIONS, clean, options } from "./clean.js";
 export type { Options } from "./clean.js";
 export { Lexicon } from "./lexicon.js";
 export type { Entry, EntryInput } from "./lexicon.js";
+export { listLexicons, loadLexicon } from "./lexicons/index.js";
 export { prepare } from "./pipeline.js";
 export type { Prepared, PrepareInit } from "./pipeline.js";
 export { listProfiles, loadProfile, resolveProfile } from "./profiles/index.js";

package/dist/index.js

@@ -7,6 +7,7 @@
 export { Segmenter, pack, splitSentences } from "./chunk.js";
 export { DEFAULT_OPTIONS, clean, options } from "./clean.js";
 export { Lexicon } from "./lexicon.js";
+export { listLexicons, loadLexicon } from "./lexicons/index.js";
 export { prepare } from "./pipeline.js";
 export { listProfiles, loadProfile, resolveProfile } from "./profiles/index.js";
 export { verbalize } from "./verbalize/index.js";

package/dist/integrations/livekit.d.ts

@@ -1,9 +1,11 @@
 /** speechready as a LiveKit Agents text transform.
  *
  * LiveKit Agents for Node passes the LLM's text stream through `ttsTextTransforms`
- * before synthesis. Each transform is `(AsyncIterable<string>) => AsyncIterable<string>`.
- * This one segments the stream into sentences as they are confirmed, runs each
- * through `prepare`, and yields the result.
+ * before synthesis. Each transform is `(text: ReadableStream<string>) => ReadableStream<string>`
+ * (`TextTransform` in `@livekit/agents`), and the transforms are chained, so the
+ * return value has to be a real `ReadableStream`. This one segments the stream into
+ * sentences as they are confirmed, runs each through `prepare`, and streams the result.
+ * It also accepts any async iterable of strings as input.
  *
  *     import { textTransform } from "speechready/livekit";
  *     const session = new voice.AgentSession({
@@ -16,4 +18,5 @@ export interface TextTransformInit extends Omit<PrepareInit, "limit"> {
     /** Release a long sentence at a clause boundary once the buffer holds this many characters. */
     maxBuffer?: number | null;
 }
-export declare function textTransform(init?: TextTransformInit): (text: AsyncIterable<string>) => AsyncIterable<string>;
+export type TextInput = ReadableStream<string> | AsyncIterable<string>;
+export declare function textTransform(init?: TextTransformInit): (text: TextInput) => ReadableStream<string>;

package/dist/integrations/livekit.js

@@ -1,9 +1,11 @@
 /** speechready as a LiveKit Agents text transform.
  *
  * LiveKit Agents for Node passes the LLM's text stream through `ttsTextTransforms`
- * before synthesis. Each transform is `(AsyncIterable<string>) => AsyncIterable<string>`.
- * This one segments the stream into sentences as they are confirmed, runs each
- * through `prepare`, and yields the result.
+ * before synthesis. Each transform is `(text: ReadableStream<string>) => ReadableStream<string>`
+ * (`TextTransform` in `@livekit/agents`), and the transforms are chained, so the
+ * return value has to be a real `ReadableStream`. This one segments the stream into
+ * sentences as they are confirmed, runs each through `prepare`, and streams the result.
+ * It also accepts any async iterable of strings as input.
  *
  *     import { textTransform } from "speechready/livekit";
  *     const session = new voice.AgentSession({
@@ -17,9 +19,9 @@ export function textTransform(init = {}) {
     const { maxBuffer = null, ...prepareInit } = init;
     const locale = prepareInit.locale ?? "en-US";
     const spoken = (piece) => prepare(piece, prepareInit).text;
-    return async function* transform(text) {
+    async function* run(text) {
         const seg = new Segmenter({ locale, maxBuffer });
-        for await (const chunk of text) {
+        for await (const chunk of iterate(text)) {
             for (const piece of seg.push(chunk)) {
                 const out = spoken(piece);
                 if (out)
@@ -31,5 +33,39 @@ export function textTransform(init = {}) {
             if (out)
                 yield out + " ";
         }
+    }
+    return function transform(text) {
+        const gen = run(text);
+        return new ReadableStream({
+            async pull(controller) {
+                const { value, done } = await gen.next();
+                if (done)
+                    controller.close();
+                else
+                    controller.enqueue(value);
+            },
+            async cancel() {
+                await gen.return(undefined);
+            },
+        });
     };
 }
+/** Read a ReadableStream (which browsers do not make async-iterable) or any async iterable. */
+async function* iterate(text) {
+    if (typeof text[Symbol.asyncIterator] === "function") {
+        yield* text;
+        return;
+    }
+    const reader = text.getReader();
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            yield value;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/lexicon.js

@@ -12,6 +12,8 @@
  */
 import { SENTINEL_CLOSE, SENTINEL_OPEN, intent } from "./intents.js";
 import { W, escapeRe, escapeXml, re, sub } from "./util.js";
+import { respellSuffix } from "./verbalize/numbers_tr.js";
+const TR_SUFFIX = "(?:(['’])([a-zçğıöşü]+))?";
 export function entry(e) {
     return { ipa: "", say: "", spell: false, case_sensitive: false, ...e };
 }
@@ -71,12 +73,22 @@ export class Lexicon {
             return text;
         let work = text;
         const ordered = [...this.entries].sort((a, b) => b.word.length - a.word.length);
+        const turkish = this.locale.split("-")[0].toLowerCase() === "tr";
         for (const e of ordered) {
             const flags = e.case_sensitive ? "" : "i";
-            const pattern = re(`(?<![${W}${SENTINEL_OPEN}${SENTINEL_CLOSE}])${escapeRe(e.word)}(?![${W}])`, flags);
+            // In Turkish a respelled word's apostrophe suffix (API'yi) is refitted to the spoken form (ey pi ay'ı).
+            const refit = turkish && !!e.say && !e.ipa;
+            const suffix = refit ? TR_SUFFIX : "";
+            const pattern = re(`(?<![${W}${SENTINEL_OPEN}${SENTINEL_CLOSE}])${escapeRe(e.word)}${suffix}(?![${W}])`, flags);
             work = sub(pattern, work, (m) => {
-                intents.push(entryIntent(e, m[0]));
-                return `${SENTINEL_OPEN}${intents.length - 1}${SENTINEL_CLOSE}`;
+                let word = m[0];
+                let tail = "";
+                if (refit && m[2]) {
+                    word = word.slice(0, word.length - m[1].length - m[2].length);
+                    tail = m[1] + respellSuffix(e.say, m[2]);
+                }
+                intents.push(entryIntent(e, word));
+                return `${SENTINEL_OPEN}${intents.length - 1}${SENTINEL_CLOSE}${tail}`;
             });
         }
         return work;

package/dist/lexicons/data.d.ts

@@ -0,0 +1,4 @@
+export declare const LEXICON_DATA: Record<string, {
+    locale?: string;
+    entries?: Record<string, unknown>[];
+}>;

package/dist/lexicons/data.js

@@ -0,0 +1,293 @@
+// Generated by scripts/build-profiles.mjs from spec/lexicons. Do not edit.
+export const LEXICON_DATA = {
+    "tr-tech": {
+        "locale": "tr-TR",
+        "entries": [
+            {
+                "word": "API",
+                "say": "ey pi ay"
+            },
+            {
+                "word": "URL",
+                "say": "yu ar el"
+            },
+            {
+                "word": "URI",
+                "say": "yu ar ay"
+            },
+            {
+                "word": "AWS",
+                "say": "ey dabılyu es"
+            },
+            {
+                "word": "GCP",
+                "say": "ci si pi"
+            },
+            {
+                "word": "CPU",
+                "say": "si pi yu"
+            },
+            {
+                "word": "GPU",
+                "say": "ci pi yu"
+            },
+            {
+                "word": "SSD",
+                "say": "es es di"
+            },
+            {
+                "word": "HTML",
+                "say": "eyç ti em el"
+            },
+            {
+                "word": "CSS",
+                "say": "si es es"
+            },
+            {
+                "word": "SQL",
+                "say": "es kyu el"
+            },
+            {
+                "word": "PHP",
+                "say": "pi eyç pi"
+            },
+            {
+                "word": "HTTP",
+                "say": "eyç ti ti pi"
+            },
+            {
+                "word": "HTTPS",
+                "say": "eyç ti ti pi es"
+            },
+            {
+                "word": "JS",
+                "say": "cey es"
+            },
+            {
+                "word": "TS",
+                "say": "ti es"
+            },
+            {
+                "word": "UI",
+                "say": "yu ay"
+            },
+            {
+                "word": "UX",
+                "say": "yu eks"
+            },
+            {
+                "word": "AI",
+                "say": "ey ay"
+            },
+            {
+                "word": "ML",
+                "say": "em el"
+            },
+            {
+                "word": "LLM",
+                "say": "el el em"
+            },
+            {
+                "word": "GPT",
+                "say": "ci pi ti"
+            },
+            {
+                "word": "OCR",
+                "say": "o si ar"
+            },
+            {
+                "word": "PDF",
+                "say": "pi di ef"
+            },
+            {
+                "word": "CSV",
+                "say": "si es vi"
+            },
+            {
+                "word": "XML",
+                "say": "eks em el"
+            },
+            {
+                "word": "SDK",
+                "say": "es di key"
+            },
+            {
+                "word": "CLI",
+                "say": "si el ay"
+            },
+            {
+                "word": "IDE",
+                "say": "ay di i"
+            },
+            {
+                "word": "DNS",
+                "say": "di en es"
+            },
+            {
+                "word": "IP",
+                "say": "ay pi"
+            },
+            {
+                "word": "TCP",
+                "say": "ti si pi"
+            },
+            {
+                "word": "UDP",
+                "say": "yu di pi"
+            },
+            {
+                "word": "SSH",
+                "say": "es es eyç"
+            },
+            {
+                "word": "SSL",
+                "say": "es es el"
+            },
+            {
+                "word": "TLS",
+                "say": "ti el es"
+            },
+            {
+                "word": "VPN",
+                "say": "vi pi en"
+            },
+            {
+                "word": "VM",
+                "say": "vi em"
+            },
+            {
+                "word": "DB",
+                "say": "di bi"
+            },
+            {
+                "word": "ORM",
+                "say": "o ar em"
+            },
+            {
+                "word": "JWT",
+                "say": "cey dabılyu ti"
+            },
+            {
+                "word": "NPM",
+                "say": "en pi em"
+            },
+            {
+                "word": "UUID",
+                "say": "yu yu ay di"
+            },
+            {
+                "word": "CDN",
+                "say": "si di en"
+            },
+            {
+                "word": "TTS",
+                "say": "ti ti es"
+            },
+            {
+                "word": "STT",
+                "say": "es ti ti"
+            },
+            {
+                "word": "ASR",
+                "say": "ey es ar"
+            },
+            {
+                "word": "NLP",
+                "say": "en el pi"
+            },
+            {
+                "word": "MCP",
+                "say": "em si pi"
+            },
+            {
+                "word": "QA",
+                "say": "kyu ey"
+            },
+            {
+                "word": "PR",
+                "say": "pi ar"
+            },
+            {
+                "word": "CI",
+                "say": "si ay"
+            },
+            {
+                "word": "CD",
+                "say": "si di"
+            },
+            {
+                "word": "CRM",
+                "say": "si ar em"
+            },
+            {
+                "word": "ERP",
+                "say": "i ar pi"
+            },
+            {
+                "word": "SEO",
+                "say": "es i o"
+            },
+            {
+                "word": "KPI",
+                "say": "key pi ay"
+            },
+            {
+                "word": "CEO",
+                "say": "si i o"
+            },
+            {
+                "word": "CTO",
+                "say": "si ti o"
+            },
+            {
+                "word": "OS",
+                "say": "o es"
+            },
+            {
+                "word": "PC",
+                "say": "pi si"
+            },
+            {
+                "word": "iOS",
+                "say": "ay o es"
+            },
+            {
+                "word": "IT",
+                "say": "ay ti",
+                "case_sensitive": true
+            },
+            {
+                "word": "JSON",
+                "say": "ceyson"
+            },
+            {
+                "word": "GitHub",
+                "say": "githab"
+            },
+            {
+                "word": "Python",
+                "say": "paytın"
+            },
+            {
+                "word": "WiFi",
+                "say": "vayfay"
+            },
+            {
+                "word": "Wi-Fi",
+                "say": "vayfay"
+            },
+            {
+                "word": "Java",
+                "say": "cava"
+            },
+            {
+                "word": "Excel",
+                "say": "eksel"
+            },
+            {
+                "word": "Chrome",
+                "say": "krom"
+            }
+        ]
+    }
+};

package/dist/lexicons/index.d.ts

@@ -0,0 +1,10 @@
+/** Lexicons bundled with the package, from the repository's `spec/lexicons`.
+ *
+ *     prepare("API'yi çağır.", { locale: "tr-TR", lexicon: loadLexicon("tr-tech") }).text
+ *     prepare("API'yi çağır.", { locale: "tr-TR", lexicon: "tr-tech" }).text   // the same, by name
+ */
+import { Lexicon } from "../lexicon.js";
+/** Names of the bundled lexicons, e.g. ["tr-tech"]. */
+export declare function listLexicons(): string[];
+/** A bundled lexicon by name; a new object each call, so it can be extended. */
+export declare function loadLexicon(name: string): Lexicon;

package/dist/lexicons/index.js

@@ -0,0 +1,18 @@
+/** Lexicons bundled with the package, from the repository's `spec/lexicons`.
+ *
+ *     prepare("API'yi çağır.", { locale: "tr-TR", lexicon: loadLexicon("tr-tech") }).text
+ *     prepare("API'yi çağır.", { locale: "tr-TR", lexicon: "tr-tech" }).text   // the same, by name
+ */
+import { Lexicon } from "../lexicon.js";
+import { LEXICON_DATA } from "./data.js";
+/** Names of the bundled lexicons, e.g. ["tr-tech"]. */
+export function listLexicons() {
+    return Object.keys(LEXICON_DATA).sort();
+}
+/** A bundled lexicon by name; a new object each call, so it can be extended. */
+export function loadLexicon(name) {
+    const data = LEXICON_DATA[name];
+    if (!data)
+        throw new Error(`unknown bundled lexicon ${JSON.stringify(name)}; known: ${listLexicons().join(", ")}`);
+    return Lexicon.fromObject({ locale: data.locale, entries: (data.entries ?? []) });
+}

package/dist/pipeline.d.ts

@@ -24,8 +24,8 @@ export interface PrepareInit {
     /** Overrides the profile's request limit (null = no limit, undefined = the profile's). */
     limit?: number | null;
     options?: Partial<Options> | null;
-    /** A Lexicon, or its entries; its words are pronounced as it says. */
-    lexicon?: Lexicon | EntryInput[] | null;
+    /** A Lexicon, its entries, or the name of a bundled lexicon ("tr-tech"); its words are pronounced as it says. */
+    lexicon?: Lexicon | EntryInput[] | string | null;
 }
 /** Prepare `text` for the given provider and model.
  *

package/dist/pipeline.js

@@ -5,6 +5,7 @@ import { clean } from "./clean.js";
 import { compileText } from "./compile.js";
 import { extract, sentinelPattern } from "./intents.js";
 import { Lexicon } from "./lexicon.js";
+import { loadLexicon } from "./lexicons/index.js";
 import { resolveProfile } from "./profiles/index.js";
 import { sub } from "./util.js";
 import { verbalize } from "./verbalize/index.js";
@@ -16,7 +17,9 @@ import "./verbalize/tr.js";
  */
 export function prepare(text, init = {}) {
     const locale = init.locale ?? "en-US";
-    const lex = Array.isArray(init.lexicon) ? Lexicon.fromEntries(init.lexicon, locale) : init.lexicon ?? null;
+    const lex = typeof init.lexicon === "string" ? loadLexicon(init.lexicon)
+        : Array.isArray(init.lexicon) ? Lexicon.fromEntries(init.lexicon, locale)
+            : init.lexicon ?? null;
     const prof = init.profile ?? resolveProfile(init.provider ?? null, init.model ?? null);
     const rec = new Recorder();
     let [work, intents] = extract(text);

package/dist/verbalize/numbers_tr.d.ts

@@ -16,6 +16,12 @@ export declare function soften(word: string): string;
 export declare function attach(word: string, suffix: string): string;
 /** Re-harmonise a suffix written against an abbreviation (TL'ye, 1/4'ü) for the spoken word (liraya, çeyreği). */
 export declare function reharmonize(word: string, suffix: string): string;
+/** The suffix a writer attached to an abbreviation (API'yi), refitted to how the word is said (ey pi ay -> 'ı).
+ *
+ * Harmony follows the last spoken word, and the buffer consonant follows whether it
+ * ends in a vowel: GPU'yu -> ci pi yu'yu, API'si -> ey pi ay'ı.
+ */
+export declare function respellSuffix(word: string, suffix: string): string;
 /** üçüncü, dördüncü, yirmi birinci. */
 export declare function ordinal(n: number): string;
 /** üç -> üçte, dört -> dörtte, on -> onda, beş -> beşte. */

package/dist/verbalize/numbers_tr.js

@@ -99,6 +99,25 @@ export function reharmonize(word, suffix) {
     const four = harmonyI(word);
     return Array.from(suffix).map((ch) => ("ae".includes(ch) ? two : "ıiuü".includes(ch) ? four : ch)).join("");
 }
+/** The suffix a writer attached to an abbreviation (API'yi), refitted to how the word is said (ey pi ay -> 'ı).
+ *
+ * Harmony follows the last spoken word, and the buffer consonant follows whether it
+ * ends in a vowel: GPU'yu -> ci pi yu'yu, API'si -> ey pi ay'ı.
+ */
+export function respellSuffix(word, suffix) {
+    if (!suffix)
+        return suffix;
+    const last = word.slice(word.lastIndexOf(" ") + 1);
+    let s = reharmonize(last, suffix);
+    const endsInVowel = VOWELS.includes(last[last.length - 1]);
+    if ("sy".includes(s[0]) && s.length > 1 && VOWELS.includes(s[1]) && !endsInVowel) {
+        s = s.slice(1);
+    }
+    else if (VOWELS.includes(s[0]) && endsInVowel) {
+        s = "y" + s;
+    }
+    return s;
+}
 /** üçüncü, dördüncü, yirmi birinci. */
 export function ordinal(n) {
     const words = cardinal(n);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.2.0";
+export declare const version = "0.3.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/build-profiles.mjs from package.json. Do not edit.
-export const version = "0.2.0";
+export const version = "0.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speechready",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Prepare text for text-to-speech: clean LLM output, verbalize ambiguous tokens, compile pauses to each provider's syntax, chunk under model limits.",
   "type": "module",
   "main": "./dist/index.js",