speechflow 0.9.8 → 1.0.0

package/src/speechflow.ts

@@ -8,17 +8,24 @@
 import path                     from "node:path"
 import Stream                   from "node:stream"
 import { EventEmitter }         from "node:events"
+import http                     from "node:http"
+import * as HAPI                from "@hapi/hapi"
+import WebSocket                from "ws"
+import HAPIWebSocket            from "hapi-plugin-websocket"
+import HAPIHeader               from "hapi-plugin-header"
 
 /*  external dependencies  */
 import { DateTime }             from "luxon"
 import CLIio                    from "cli-io"
 import yargs                    from "yargs"
+import { hideBin }              from "yargs/helpers"
 import jsYAML                   from "js-yaml"
 import FlowLink                 from "flowlink"
 import objectPath               from "object-path"
 import installedPackages        from "installed-packages"
 import dotenvx                  from "@dotenvx/dotenvx"
 import syspath                  from "syspath"
+import * as arktype             from "arktype"
 
 /*  internal dependencies  */
 import SpeechFlowNode           from "./speechflow-node"
@@ -27,6 +34,15 @@ import pkg                      from "../package.json"
 /*  central CLI context  */
 let cli: CLIio | null = null
 
+type wsPeerCtx = {
+    peer: string
+}
+type wsPeerInfo = {
+    ctx:        wsPeerCtx
+    ws:         WebSocket
+    req:        http.IncomingMessage
+}
+
 /*  establish asynchronous environment  */
 ;(async () => {
     /*  determine system paths  */
@@ -36,6 +52,7 @@ let cli: CLIio | null = null
     })
 
     /*  parse command-line arguments  */
+    const coerce = (arg: string) => Array.isArray(arg) ? arg[arg.length - 1] : arg
     const args = await yargs()
         /* eslint @stylistic/indent: off */
         .usage(
@@ -43,34 +60,95 @@ let cli: CLIio | null = null
             "[-h|--help] " +
             "[-V|--version] " +
             "[-v|--verbose <level>] " +
+            "[-a|--address <ip-address>] " +
+            "[-p|--port <tcp-port>] " +
             "[-C|--cache <directory>] " +
             "[-e|--expression <expression>] " +
             "[-f|--file <file>] " +
             "[-c|--config <id>@<yaml-config-file>] " +
             "[<argument> [...]]"
         )
-        .help("h").alias("h", "help").default("h", false)
-            .describe("h", "show usage help")
-        .boolean("V").alias("V", "version").default("V", false)
-            .describe("V", "show program version information")
-        .string("v").nargs("v", 1).alias("v", "log-level").default("v", "warning")
-            .describe("v", "level for verbose logging ('none', 'error', 'warning', 'info', 'debug')")
-        .string("C").nargs("C", 1).alias("C", "cache").default("C", path.join(dataDir, "cache"))
-            .describe("C", "directory for cached files (primarily AI model files)")
-        .string("e").nargs("e", 1).alias("e", "expression").default("e", "")
-            .describe("e", "FlowLink expression string")
-        .string("f").nargs("f", 1).alias("f", "file").default("f", "")
-            .describe("f", "FlowLink expression file")
-        .string("c").nargs("c", 1).alias("c", "config-file").default("c", "")
-            .describe("c", "FlowLink expression reference into YAML file (in format <id>@<file>)")
+        .option("V", {
+            alias:    "version",
+            type:     "boolean",
+            array:    false,
+            coerce,
+            default:  false,
+            describe: "show program version information"
+        })
+        .option("v", {
+            alias:    "log-level",
+            type:     "string",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  "warning",
+            describe: "level for verbose logging ('none', 'error', 'warning', 'info', 'debug')"
+        })
+        .option("a", {
+            alias:    "address",
+            type:     "string",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  "0.0.0.0",
+            describe: "IP address for REST/WebSocket API"
+        })
+        .option("p", {
+            alias:    "port",
+            type:     "number",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  8484,
+            describe: "TCP port for REST/WebSocket API"
+        })
+        .option("C", {
+            alias:    "cache",
+            type:     "string",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  path.join(dataDir, "cache"),
+            describe: "directory for cached files (primarily AI model files)"
+        })
+        .option("e", {
+            alias:    "expression",
+            type:     "string",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  "",
+            describe: "FlowLink expression string"
+        })
+        .option("f", {
+            alias:    "file",
+            type:     "string",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  "",
+            describe: "FlowLink expression file"
+        })
+        .option("c", {
+            alias:    "config",
+            type:     "string",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  "",
+            describe: "FlowLink expression reference into YAML file (in format <id>@<file>)"
+        })
+        .help("h", "show usage help")
+        .alias("h", "help")
+        .showHelpOnFail(true)
         .version(false)
         .strict()
-        .showHelpOnFail(true)
         .demand(0)
-        .parse(process.argv.slice(2))
+        .parse(hideBin(process.argv))
 
     /*  short-circuit version request  */
-    if (args.version) {
+    if (args.V) {
         process.stderr.write(`SpeechFlow ${pkg["x-stdver"]} (${pkg["x-release"]}) <${pkg.homepage}>\n`)
         process.stderr.write(`${pkg.description}\n`)
         process.stderr.write(`Copyright (c) 2024-2025 ${pkg.author.name} <${pkg.author.url}>\n`)
@@ -81,7 +159,7 @@ let cli: CLIio | null = null
     /*  establish CLI environment  */
     cli = new CLIio({
         encoding:  "utf8",
-        logLevel:  args.logLevel,
+        logLevel:  args.v,
         logTime:   true,
         logPrefix: pkg.name
     })
@@ -112,28 +190,28 @@ let cli: CLIio | null = null
 
     /*  sanity check usage  */
     let n = 0
-    if (typeof args.expression     === "string" && args.expression     !== "") n++
-    if (typeof args.expressionFile === "string" && args.expressionFile !== "") n++
-    if (typeof args.configFile     === "string" && args.configFile     !== "") n++
+    if (typeof args.e === "string" && args.e !== "") n++
+    if (typeof args.f === "string" && args.f !== "") n++
+    if (typeof args.c === "string" && args.c !== "") n++
     if (n !== 1)
         throw new Error("cannot use more than one FlowLink specification source (either option -e, -f or -c)")
 
     /*  read configuration  */
     let config = ""
-    if (typeof args.expression === "string" && args.expression !== "")
-        config = args.expression
-    else if (typeof args.expressionFile === "string" && args.expressionFile !== "")
-        config = await cli.input(args.expressionFile, { encoding: "utf8" })
-    else if (typeof args.configFile === "string" && args.configFile !== "") {
-        const m = args.configFile.match(/^(.+?)@(.+)$/)
+    if (typeof args.e === "string" && args.e !== "")
+        config = args.e
+    else if (typeof args.f === "string" && args.f !== "")
+        config = await cli.input(args.f, { encoding: "utf8" })
+    else if (typeof args.c === "string" && args.c !== "") {
+        const m = args.c.match(/^(.+?)@(.+)$/)
         if (m === null)
-            throw new Error("invalid configuration file specification (expected \"<key>@<yaml-config-file>\")")
-        const [ , key, file ] = m
+            throw new Error("invalid configuration file specification (expected \"<id>@<yaml-config-file>\")")
+        const [ , id, file ] = m
         const yaml = await cli.input(file, { encoding: "utf8" })
         const obj: any = jsYAML.load(yaml)
-        if (obj[key] === undefined)
-            throw new Error(`no such key "${key}" found in configuration file`)
-        config = obj[key] as string
+        if (obj[id] === undefined)
+            throw new Error(`no such id "${id}" found in configuration file`)
+        config = obj[id] as string
     }
 
     /*  track the available SpeechFlow nodes  */
@@ -143,13 +221,18 @@ let cli: CLIio | null = null
     const pkgsI = [
         "./speechflow-node-a2a-ffmpeg.js",
         "./speechflow-node-a2a-wav.js",
+        "./speechflow-node-a2a-mute.js",
+        "./speechflow-node-a2a-meter.js",
+        "./speechflow-node-a2a-vad.js",
         "./speechflow-node-a2t-deepgram.js",
         "./speechflow-node-t2a-elevenlabs.js",
+        "./speechflow-node-t2a-kokoro.js",
         "./speechflow-node-t2t-deepl.js",
-        "./speechflow-node-t2t-format.js",
-        "./speechflow-node-t2t-gemma.js",
-        "./speechflow-node-t2t-opus.js",
+        "./speechflow-node-t2t-openai.js",
+        "./speechflow-node-t2t-ollama.js",
+        "./speechflow-node-t2t-transformers.js",
         "./speechflow-node-t2t-subtitle.js",
+        "./speechflow-node-t2t-format.js",
         "./speechflow-node-x2x-trace.js",
         "./speechflow-node-xio-device.js",
         "./speechflow-node-xio-file.js",
@@ -191,16 +274,16 @@ let cli: CLIio | null = null
             cli!.log("debug", msg)
         }
     })
-    let nodenum = 1
     const variables = { argv: args._, env: process.env }
     const graphNodes = new Set<SpeechFlowNode>()
+    const nodeNums = new Map<typeof SpeechFlowNode, number>()
     const cfg = {
         audioChannels:     1,
         audioBitDepth:     16,
         audioLittleEndian: true,
         audioSampleRate:   48000,
         textEncoding:      "utf8",
-        cacheDir:          args.cache
+        cacheDir:          args.C
     }
     let ast: unknown
     try {
@@ -229,17 +312,19 @@ let cli: CLIio | null = null
                     throw new Error(`unknown node "${id}"`)
                 let node: SpeechFlowNode
                 try {
-                    node = new nodes[id](`${id}[${nodenum}]`, cfg, opts, args)
+                    let num = nodeNums.get(nodes[id]) ?? 0
+                    nodeNums.set(nodes[id], ++num)
+                    const name = num === 1 ? id : `${id}:${num}`
+                    node = new nodes[id](name, cfg, opts, args)
                 }
                 catch (err) {
                     /*  fatal error  */
                     if (err instanceof Error)
-                        cli!.log("error", `creation of "${id}[${nodenum}]" node failed: ${err.message}`)
+                        cli!.log("error", `creation of <${id}> node failed: ${err.message}`)
                     else
-                        cli!.log("error", `creation of "${id}"[${nodenum}] node failed: ${err}`)
+                        cli!.log("error", `creation of <${id}> node failed: ${err}`)
                     process.exit(1)
                 }
-                nodenum++
                 const params = Object.keys(node.params)
                     .map((key) => `${key}: ${JSON.stringify(node.params[key])}`).join(", ")
                 cli!.log("info", `create node "${node.id}" (${params})`)
@@ -254,9 +339,9 @@ let cli: CLIio | null = null
     }
     catch (err) {
         if (err instanceof Error && err.name === "FlowLinkError")
-            cli!.log("error", `failed to materialize SpeechFlow configuration: ${err.toString()}"`)
+            cli!.log("error", `failed to materialize SpeechFlow configuration: ${err.toString()}`)
         else if (err instanceof Error)
-            cli!.log("error", `failed to materialize SpeechFlow configuration: ${err.message}"`)
+            cli!.log("error", `failed to materialize SpeechFlow configuration: ${err.message}`)
         else
             cli!.log("error", "failed to materialize SpeechFlow configuration: internal error")
         process.exit(1)
@@ -357,8 +442,152 @@ let cli: CLIio | null = null
         })
     }
 
+    /*  define external request/response structure  */
+    const requestValidator = arktype.type({
+        request: "string",
+        node:    "string",
+        args:    "unknown[]"
+    })
+
+    /*  forward external request to target node in graph  */
+    const consumeExternalRequest = async (_req: any) => {
+        const req = requestValidator(_req)
+        if (req instanceof arktype.type.errors)
+            throw new Error(`invalid request: ${req.summary}`)
+        if (req.request !== "COMMAND")
+            throw new Error("invalid external request (command expected)")
+        const name = req.node as string
+        const args = req.args as any[]
+        const foundNode = Array.from(graphNodes).find((node) => node.id === name)
+        if (foundNode === undefined)
+            cli!.log("warning", `external request failed: no such node <${name}>`)
+        else {
+            await foundNode.receiveRequest(args).catch((err: Error) => {
+                cli!.log("warning", `external request to node <${name}> failed: ${err}`)
+                throw new Error(`external request to node <${name}> failed: ${err}`)
+            })
+        }
+    }
+
+    /*  establish REST/WebSocket API  */
+    const wsPeers = new Map<string, wsPeerInfo>()
+    const hapi = new HAPI.Server({
+        address: args.a,
+        port:    args.p
+    })
+    await hapi.register({ plugin: HAPIHeader, options: { Server: `${pkg.name}/${pkg.version}` } })
+    await hapi.register({ plugin: HAPIWebSocket })
+    hapi.events.on("response", (request: HAPI.Request) => {
+        let protocol = `HTTP/${request.raw.req.httpVersion}`
+        const ws = request.websocket()
+        if (ws.mode === "websocket") {
+            const wsVersion = (ws.ws as any).protocolVersion ??
+                request.headers["sec-websocket-version"] ?? "13?"
+            protocol = `WebSocket/${wsVersion}+${protocol}`
+        }
+        const msg =
+            "remote="   + request.info.remoteAddress + ", " +
+            "method="   + request.method.toUpperCase() + ", " +
+            "url="      + request.url.pathname + ", " +
+            "protocol=" + protocol + ", " +
+            "response=" + ("statusCode" in request.response ? request.response.statusCode : "<unknown>")
+        cli!.log("info", `HAPI: request: ${msg}`)
+    })
+    hapi.events.on({ name: "request", channels: [ "error" ] }, (request: HAPI.Request, event: HAPI.RequestEvent, tags: { [key: string]: true }) => {
+        if (event.error instanceof Error)
+            cli!.log("error", `HAPI: request-error: ${event.error.message}`)
+        else
+            cli!.log("error", `HAPI: request-error: ${event.error}`)
+    })
+    hapi.events.on("log", (event: HAPI.LogEvent, tags: { [key: string]: true }) => {
+        if (tags.error) {
+            const err = event.error
+            if (err instanceof Error)
+                cli!.log("error", `HAPI: log: ${err.message}`)
+            else
+                cli!.log("error", `HAPI: log: ${err}`)
+        }
+    })
+    hapi.route({
+        method: "GET",
+        path:   "/api/{req}/{node}/{params*}",
+        options: {
+        },
+        handler: (request: HAPI.Request, h: HAPI.ResponseToolkit) => {
+            const peer = request.info.remoteAddress
+            const req = {
+                request: request.params.req,
+                node:    request.params.node,
+                args:    (request.params.params as string ?? "").split("/").filter((seg) => seg !== "")
+            }
+            cli!.log("info", `HAPI: peer ${peer}: GET: ${JSON.stringify(req)}`)
+            return consumeExternalRequest(req).then(() => {
+                return h.response({ response: "OK" }).code(200)
+            }).catch((err) => {
+                return h.response({ response: "ERROR", data: err.message }).code(417)
+            })
+        }
+    })
+    hapi.route({
+        method: "POST",
+        path:   "/api",
+        options: {
+            payload: {
+                output: "data",
+                parse:  true,
+                allow:  "application/json"
+            },
+            plugins: {
+                websocket: {
+                    autoping: 30 * 1000,
+                    connect: (args: any) => {
+                        const ctx: wsPeerCtx            = args.ctx
+                        const ws:  WebSocket            = args.ws
+                        const req: http.IncomingMessage = args.req
+                        const peer = `${req.socket.remoteAddress}:${req.socket.remotePort}`
+                        ctx.peer = peer
+                        wsPeers.set(peer, { ctx, ws, req })
+                        cli!.log("info", `HAPI: WebSocket: connect: peer ${peer}`)
+                    },
+                    disconnect: (args: any) => {
+                        const ctx: wsPeerCtx = args.ctx
+                        const peer = ctx.peer
+                        wsPeers.delete(peer)
+                        cli!.log("info", `HAPI: WebSocket: disconnect: peer ${peer}`)
+                    }
+                }
+            }
+        },
+        handler: (request: HAPI.Request, h: HAPI.ResponseToolkit) => {
+            /*  on WebSocket message transfer  */
+            const peer = request.info.remoteAddress
+            const req = requestValidator(request.payload)
+            if (req instanceof arktype.type.errors)
+                return h.response({ response: "ERROR", data: `invalid request: ${req.summary}` }).code(417)
+            cli!.log("info", `HAPI: peer ${peer}: POST: ${JSON.stringify(req)}`)
+            return consumeExternalRequest(req).then(() => {
+                return h.response({ response: "OK" }).code(200)
+            }).catch((err: Error) => {
+                return h.response({ response: "ERROR", data: err.message }).code(417)
+            })
+        }
+    })
+    await hapi.start()
+    cli!.log("info", `HAPI: started REST/WebSocket network service: http://${args.address}:${args.port}`)
+
+    /*  hook for sendResponse method of nodes  */
+    for (const node of graphNodes) {
+        node.on("send-response", (args: any[]) => {
+            const data = JSON.stringify({ response: "NOTIFY", node: node.id, args })
+            for (const [ peer, info ] of wsPeers.entries()) {
+                cli!.log("info", `HAPI: peer ${peer}: ${data}`)
+                info.ws.send(data)
+            }
+        })
+    }
+
     /*  start of internal stream processing  */
-    cli!.log("info", "everything established -- stream processing in SpeechFlow graph starts")
+    cli!.log("info", "**** everything established -- stream processing in SpeechFlow graph starts ****")
 
     /*  gracefully shutdown process  */
     let shuttingDown = false
@@ -367,9 +596,13 @@ let cli: CLIio | null = null
             return
         shuttingDown = true
         if (signal === "finished")
-            cli!.log("info", "streams of all nodes finished -- shutting down service")
+            cli!.log("info", "**** streams of all nodes finished -- shutting down service ****")
         else
-            cli!.log("warning", `received signal ${signal} -- shutting down service`)
+            cli!.log("warning", `**** received signal ${signal} -- shutting down service ****`)
+
+        /*  shutdown HAPI service  */
+        cli!.log("info", `HAPI: stopping REST/WebSocket network service: http://${args.address}:${args.port}`)
+        await hapi.stop()
 
         /*  graph processing: PASS 1: disconnect node streams  */
         for (const node of graphNodes) {

package/dst/speechflow-node-deepgram.d.ts

@@ -1,12 +0,0 @@
-import SpeechFlowNode from "./speechflow-node";
-export default class SpeechFlowNodeDeepgram extends SpeechFlowNode {
-    static name: string;
-    private dg;
-    constructor(id: string, cfg: {
-        [id: string]: any;
-    }, opts: {
-        [id: string]: any;
-    }, args: any[]);
-    open(): Promise<void>;
-    close(): Promise<void>;
-}