speechflow 1.4.5 → 1.5.1

package/speechflow-cli/src/speechflow-node-t2t-awstranslate.ts

@@ -0,0 +1,153 @@
+/*
+**  SpeechFlow - Speech Processing Flow Graph
+**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+
+/*  standard dependencies  */
+import Stream from "node:stream"
+
+/*  external dependencies  */
+import { TranslateClient, TranslateTextCommand } from "@aws-sdk/client-translate"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as utils                          from "./speechflow-utils"
+
+/*  SpeechFlow node for AWS Translate text-to-text translations  */
+export default class SpeechFlowNodeAWSTranslate extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "awstranslate"
+
+    /*  internal state  */
+    private client: TranslateClient | null = null
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            key:      { type: "string",         val: process.env.SPEECHFLOW_AMAZON_KEY },
+            secKey:   { type: "string",         val: process.env.SPEECHFLOW_AMAZON_KEY_SEC },
+            region:   { type: "string",         val: "eu-central-1" },
+            src:      { type: "string", pos: 0, val: "de", match: /^(?:de|en|fr|it)$/ },
+            dst:      { type: "string", pos: 1, val: "en", match: /^(?:de|en|fr|it)$/ }
+        })
+
+        /*  sanity check parameters  */
+        if (!this.params.key)
+            throw new Error("AWS Access Key not configured")
+        if (!this.params.secKey)
+            throw new Error("AWS Secret Access Key not configured")
+
+        /*  sanity check situation  */
+        if (this.params.src === this.params.dst)
+            throw new Error("source and destination languages cannot be the same")
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "text"
+    }
+
+    /*  one-time status of node  */
+    async status () {
+        return {}
+    }
+
+    /*  open node  */
+    async open () {
+        /*  connect to Amazon Translate API  */
+        this.client = new TranslateClient({
+            region: this.params.region,
+            credentials: {
+                accessKeyId:     this.params.key,
+                secretAccessKey: this.params.secKey
+            }
+        })
+        if (this.client === null)
+            throw new Error("failed to establish Amazon Translate client")
+
+        /*  provide text-to-text translation  */
+        const maxRetries = 10
+        const translate = async (text: string): Promise<string> => {
+            let attempt = 0
+            let lastError: unknown
+            while (attempt < maxRetries) {
+                try {
+                    const cmd = new TranslateTextCommand({
+                        SourceLanguageCode: this.params.src,
+                        TargetLanguageCode: this.params.dst,
+                        Text: text,
+                        Settings: {
+                            Formality: "INFORMAL",
+                            Brevity:   "ON"
+                        }
+                    })
+                    const out = await this.client!.send(cmd)
+                    return (out.TranslatedText ?? "").trim()
+                } catch (e: any) {
+                    lastError = e
+                    attempt += 1
+
+                    /*  simple backoff for transient errors  */
+                    const retriable =
+                        e?.name === "ThrottlingException" ||
+                        e?.name === "ServiceUnavailableException" ||
+                        e?.$retryable === true
+                    if (!retriable || attempt >= maxRetries)
+                        break
+                    const delayMs = Math.min(1000 * Math.pow(2, attempt - 1), 5000)
+                    await new Promise((resolve) => setTimeout(resolve, delayMs))
+                }
+            }
+            throw lastError instanceof Error ? lastError : new Error(String(lastError))
+        }
+
+        /*  establish a duplex stream and connect it to AWS Translate  */
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            highWaterMark:      1,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
+                else if (chunk.payload === "") {
+                    this.push(chunk)
+                    callback()
+                }
+                else {
+                    translate(chunk.payload).then((payload) => {
+                        const chunkNew = chunk.clone()
+                        chunkNew.payload = payload
+                        this.push(chunkNew)
+                        callback()
+                    }).catch((error: unknown) => {
+                        callback(utils.ensureError(error))
+                    })
+                }
+            },
+            final (callback) {
+                this.push(null)
+                callback()
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  close Amazon Translate connection  */
+        if (this.client !== null) {
+            this.client.destroy()
+            this.client = null
+        }
+
+        /*  close stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+    }
+}
+

package/speechflow-cli/src/speechflow-node-t2t-deepl.ts

@@ -12,6 +12,7 @@ import * as DeepL from "deepl-node"
 
 /*  internal dependencies  */
 import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as utils                          from "./speechflow-utils"
 
 /*  SpeechFlow node for DeepL text-to-text translations  */
 export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
@@ -28,8 +29,8 @@ export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
         /*  declare node configuration parameters  */
         this.configure({
             key:      { type: "string", val: process.env.SPEECHFLOW_DEEPL_KEY ?? "" },
-            src:      { type: "string", pos: 0, val: "de",      match: /^(?:de|en)$/ },
-            dst:      { type: "string", pos: 1, val: "en",      match: /^(?:de|en)$/ },
+            src:      { type: "string", pos: 0, val: "de",      match: /^(?:de|en|fr|it)$/ },
+            dst:      { type: "string", pos: 1, val: "en",      match: /^(?:de|en|fr|it)$/ },
             optimize: { type: "string", pos: 2, val: "latency", match: /^(?:latency|quality)$/ }
         })
 
@@ -83,21 +84,19 @@ export default class SpeechFlowNodeDeepL extends SpeechFlowNode {
             transform (chunk: SpeechFlowChunk, encoding, callback) {
                 if (Buffer.isBuffer(chunk.payload))
                     callback(new Error("invalid chunk payload type"))
+                else if (chunk.payload === "") {
+                    this.push(chunk)
+                    callback()
+                }
                 else {
-                    if (chunk.payload === "") {
-                        this.push(chunk)
+                    translate(chunk.payload).then((payload) => {
+                        const chunkNew = chunk.clone()
+                        chunkNew.payload = payload
+                        this.push(chunkNew)
                         callback()
-                    }
-                    else {
-                        translate(chunk.payload).then((payload) => {
-                            const chunkNew = chunk.clone()
-                            chunkNew.payload = payload
-                            this.push(chunkNew)
-                            callback()
-                        }).catch((err) => {
-                            callback(err)
-                        })
-                    }
+                    }).catch((error: unknown) => {
+                        callback(utils.ensureError(error))
+                    })
                 }
             },
             final (callback) {

package/speechflow-cli/src/speechflow-node-t2t-format.ts

@@ -35,7 +35,7 @@ export default class SpeechFlowNodeFormat extends SpeechFlowNode {
     /*  open node  */
     async open () {
         /*  provide text-to-text formatter  */
-        const format = async (text: string) => {
+        const format = (text: string) => {
             text = wrapText(text, this.params.width)
             text = text.replace(/([^\n])$/, "$1\n")
             return text
@@ -50,21 +50,16 @@ export default class SpeechFlowNodeFormat extends SpeechFlowNode {
             transform (chunk: SpeechFlowChunk, encoding, callback) {
                 if (Buffer.isBuffer(chunk.payload))
                     callback(new Error("invalid chunk payload type"))
+                else if (chunk.payload === "") {
+                    this.push(chunk)
+                    callback()
+                }
                 else {
-                    if (chunk.payload === "") {
-                        this.push(chunk)
-                        callback()
-                    }
-                    else {
-                        format(chunk.payload).then((payload) => {
-                            const chunkNew = chunk.clone()
-                            chunkNew.payload = payload
-                            this.push(chunkNew)
-                            callback()
-                        }).catch((err) => {
-                            callback(err)
-                        })
-                    }
+                    const payload = format(chunk.payload)
+                    const chunkNew = chunk.clone()
+                    chunkNew.payload = payload
+                    this.push(chunkNew)
+                    callback()
                 }
             },
             final (callback) {

package/speechflow-cli/src/speechflow-node-t2t-google.ts

@@ -0,0 +1,133 @@
+/*
+**  SpeechFlow - Speech Processing Flow Graph
+**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+
+/*  standard dependencies  */
+import Stream from "node:stream"
+
+/*  external dependencies  */
+import { TranslationServiceClient } from "@google-cloud/translate"
+import * as arktype                 from "arktype"
+
+/*  internal dependencies  */
+import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as utils                          from "./speechflow-utils"
+
+/*  SpeechFlow node for Google Translate text-to-text translations  */
+export default class SpeechFlowNodeGoogle extends SpeechFlowNode {
+    /*  declare official node name  */
+    public static name = "google"
+
+    /*  internal state  */
+    private client: TranslationServiceClient | null = null
+
+    /*  construct node  */
+    constructor (id: string, cfg: { [ id: string ]: any }, opts: { [ id: string ]: any }, args: any[]) {
+        super(id, cfg, opts, args)
+
+        /*  declare node configuration parameters  */
+        this.configure({
+            key: { type: "string",         val: process.env.SPEECHFLOW_GOOGLE_KEY ?? "" },
+            src: { type: "string", pos: 0, val: "de", match: /^(?:de|en|fr|it)$/ },
+            dst: { type: "string", pos: 1, val: "en", match: /^(?:de|en|fr|it)$/ }
+        })
+
+        /*  validate API key and project  */
+        if (this.params.key === "")
+            throw new Error("Google Cloud API credentials JSON key is required")
+
+        /*  sanity check situation  */
+        if (this.params.src === this.params.dst)
+            throw new Error("source and destination languages cannot be the same")
+
+        /*  declare node input/output format  */
+        this.input  = "text"
+        this.output = "text"
+    }
+
+    /*  one-time status of node  */
+    async status () {
+        return {}
+    }
+
+    /*  open node  */
+    async open () {
+        /*  instantiate Google Translate client  */
+        const data = utils.run("Google Cloud API credentials key", () =>
+            JSON.parse(this.params.key))
+        const credentials = utils.importObject("Google Cloud API credentials key",
+            data,
+            arktype.type({
+                project_id:   "string",
+                private_key:  "string",
+                client_email: "string",
+            })
+        )
+        this.client = new TranslationServiceClient({
+            credentials: {
+                private_key:  credentials.private_key,
+                client_email: credentials.client_email
+            },
+            projectId: credentials.project_id
+        })
+
+        /*  provide text-to-text translation  */
+        const translate = utils.runner("Google Translate API", async (text: string) => {
+            const [ response ] = await this.client!.translateText({
+                parent:   `projects/${credentials.project_id}/locations/global`,
+                contents: [ text ],
+                mimeType: "text/plain",
+                sourceLanguageCode: this.params.src,
+                targetLanguageCode: this.params.dst
+            })
+            return response.translations?.[0]?.translatedText ?? text
+        })
+
+        /*  establish a duplex stream and connect it to Google Translate  */
+        this.stream = new Stream.Transform({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            decodeStrings:      false,
+            highWaterMark:      1,
+            transform (chunk: SpeechFlowChunk, encoding, callback) {
+                if (Buffer.isBuffer(chunk.payload))
+                    callback(new Error("invalid chunk payload type"))
+                else if (chunk.payload === "") {
+                    this.push(chunk)
+                    callback()
+                }
+                else {
+                    translate(chunk.payload).then((payload) => {
+                        const chunkNew = chunk.clone()
+                        chunkNew.payload = payload
+                        this.push(chunkNew)
+                        callback()
+                    }).catch((error: unknown) => {
+                        callback(utils.ensureError(error))
+                    })
+                }
+            },
+            final (callback) {
+                this.push(null)
+                callback()
+            }
+        })
+    }
+
+    /*  close node  */
+    async close () {
+        /*  close stream  */
+        if (this.stream !== null) {
+            this.stream.destroy()
+            this.stream = null
+        }
+
+        /*  shutdown Google Translate client  */
+        if (this.client !== null) {
+            this.client.close()
+            this.client = null
+        }
+    }
+}

package/speechflow-cli/src/speechflow-node-t2t-ollama.ts

@@ -8,10 +8,11 @@
 import Stream     from "node:stream"
 
 /*  external dependencies  */
-import { Ollama } from "ollama"
+import { Ollama, type ListResponse } from "ollama"
 
 /*  internal dependencies  */
 import SpeechFlowNode, { SpeechFlowChunk } from "./speechflow-node"
+import * as utils                          from "./speechflow-utils"
 
 /*  internal utility types  */
 type ConfigEntry = { systemPrompt: string, chat: Array<{ role: string, content: string }> }
@@ -49,12 +50,12 @@ export default class SpeechFlowNodeOllama extends SpeechFlowNode {
                 "Focus ONLY on the word spelling.\n" +
                 "The text you have to correct is:\n",
             chat: [
-                { role: "user",   content: "I luve my wyfe" },
-                { role: "system", content: "I love my wife." },
-                { role: "user",   content: "The weether is wunderfull!" },
-                { role: "system", content: "The weather is wonderful!" },
-                { role: "user",   content: "The live awesome but I'm hungry." },
-                { role: "system", content: "The live is awesome, but I'm hungry." }
+                { role: "user",      content: "I luve my wyfe" },
+                { role: "assistant", content: "I love my wife." },
+                { role: "user",      content: "The weether is wunderfull!" },
+                { role: "assistant", content: "The weather is wonderful!" },
+                { role: "user",      content: "The life awesome but I'm hungry." },
+                { role: "assistant", content: "The life is awesome, but I'm hungry." }
             ]
         },
 
@@ -81,12 +82,12 @@ export default class SpeechFlowNodeOllama extends SpeechFlowNode {
                 "Fokussiere dich NUR auf die Rechtschreibung der Wörter.\n" +
                 "Der von dir zu korrigierende Text ist:\n",
             chat: [
-                { role: "user",   content: "Ich ljebe meine Frao" },
-                { role: "system", content: "Ich liebe meine Frau." },
-                { role: "user",   content: "Die Wedter ist wunderschoen." },
-                { role: "system", content: "Das Wetter ist wunderschön." },
-                { role: "user",   content: "Das Leben einfach großartig aber ich bin hungrig." },
-                { role: "system", content: "Das Leben ist einfach großartig, aber ich bin hungrig." }
+                { role: "user",      content: "Ich ljebe meine Frao" },
+                { role: "assistant", content: "Ich liebe meine Frau." },
+                { role: "user",      content: "Die Wedter ist wunderschoen." },
+                { role: "assistant", content: "Das Wetter ist wunderschön." },
+                { role: "user",      content: "Das Leben einfach großartig aber ich bin hungrig." },
+                { role: "assistant", content: "Das Leben ist einfach großartig, aber ich bin hungrig." }
             ]
         },
 
@@ -106,12 +107,12 @@ export default class SpeechFlowNodeOllama extends SpeechFlowNode {
                 "Preserve the original meaning, tone, and nuance.\n" +
                 "Directly translate text from English (EN) to fluent and natural German (DE) language.\n",
             chat: [
-                { role: "user",   content: "I love my wife." },
-                { role: "system", content: "Ich liebe meine Frau." },
-                { role: "user",   content: "The weather is wonderful." },
-                { role: "system", content: "Das Wetter ist wunderschön." },
-                { role: "user",   content: "The live is awesome." },
-                { role: "system", content: "Das Leben ist einfach großartig." }
+                { role: "user",      content: "I love my wife." },
+                { role: "assistant", content: "Ich liebe meine Frau." },
+                { role: "user",      content: "The weather is wonderful." },
+                { role: "assistant", content: "Das Wetter ist wunderschön." },
+                { role: "user",      content: "The life is awesome." },
+                { role: "assistant", content: "Das Leben ist einfach großartig." }
             ]
         },
 
@@ -124,19 +125,19 @@ export default class SpeechFlowNodeOllama extends SpeechFlowNode {
                 "Do not chat.\n" +
                 "Do not show any explanations.\n" +
                 "Do not show any introduction.\n" +
-                "Do not show any preamble. \n" +
-                "Do not show any prolog. \n" +
-                "Do not show any epilog. \n" +
+                "Do not show any preamble.\n" +
+                "Do not show any prolog.\n" +
+                "Do not show any epilog.\n" +
                 "Get to the point.\n" +
                 "Preserve the original meaning, tone, and nuance.\n" +
                 "Directly translate text from German (DE) to fluent and natural English (EN) language.\n",
             chat: [
-                { role: "user",   content: "Ich liebe meine Frau." },
-                { role: "system", content: "I love my wife." },
-                { role: "user",   content: "Das Wetter ist wunderschön." },
-                { role: "system", content: "The weather is wonderful." },
-                { role: "user",   content: "Das Leben ist einfach großartig." },
-                { role: "system", content: "The live is awesome." }
+                { role: "user",      content: "Ich liebe meine Frau." },
+                { role: "assistant", content: "I love my wife." },
+                { role: "user",      content: "Das Wetter ist wunderschön." },
+                { role: "assistant", content: "The weather is wonderful." },
+                { role: "user",      content: "Das Leben ist einfach großartig." },
+                { role: "assistant", content: "The life is awesome." }
             ]
         }
     }
@@ -171,35 +172,48 @@ export default class SpeechFlowNodeOllama extends SpeechFlowNode {
         this.ollama = new Ollama({ host: this.params.api })
 
         /*  ensure the model is available  */
-        const model  = this.params.model
-        const models = await this.ollama.list()
-        const exists = models.models.some((m) => m.name === model)
+        let models: ListResponse
+        try {
+            models = await this.ollama.list()
+        }
+        catch (err) {
+            throw new Error(`failed to connect to Ollama API at ${this.params.api}: ${err}`)
+        }
+        const exists = models.models.some((m) => m.name === this.params.model)
         if (!exists) {
-            this.log("info", `Ollama: model "${model}" still not present in Ollama -- ` +
+            this.log("info", `Ollama: model "${this.params.model}" still not present in Ollama -- ` +
                 "automatically downloading model")
             let artifact = ""
             let percent  = 0
+            let lastLoggedPercent = -1
             const interval = setInterval(() => {
-                this.log("info", `downloaded ${percent.toFixed(2)}% of artifact "${artifact}"`)
+                if (percent !== lastLoggedPercent) {
+                    this.log("info", `downloaded ${percent.toFixed(2)}% of artifact "${artifact}"`)
+                    lastLoggedPercent = percent
+                }
             }, 1000)
-            const progress = await this.ollama.pull({ model, stream: true })
-            for await (const event of progress) {
-                if (event.digest)
-                    artifact = event.digest
-                if (event.completed && event.total)
-                    percent = (event.completed / event.total) * 100
+            try {
+                const progress = await this.ollama.pull({ model: this.params.model, stream: true })
+                for await (const event of progress) {
+                    if (event.digest)
+                        artifact = event.digest
+                    if (event.completed && event.total)
+                        percent = (event.completed / event.total) * 100
+                }
+            }
+            finally {
+                clearInterval(interval)
             }
-            clearInterval(interval)
         }
         else
-            this.log("info", `Ollama: model "${model}" already present in Ollama`)
+            this.log("info", `Ollama: model "${this.params.model}" already present in Ollama`)
 
         /*  provide text-to-text translation  */
         const translate = async (text: string) => {
             const key = `${this.params.src}-${this.params.dst}`
             const cfg = this.setup[key]
             const response = await this.ollama!.chat({
-                model,
+                model: this.params.model,
                 messages: [
                     { role: "system", content: cfg.systemPrompt },
                     ...cfg.chat,
@@ -237,8 +251,8 @@ export default class SpeechFlowNodeOllama extends SpeechFlowNode {
                             chunkNew.payload = payload
                             this.push(chunkNew)
                             callback()
-                        }).catch((err) => {
-                            callback(err)
+                        }).catch((error: unknown) => {
+                            callback(utils.ensureError(error))
                         })
                     }
                 }