@stacksjs/ai 0.75.374 → 0.75.377

package/README.md

@@ -96,3 +96,21 @@ For casual chit-chat with others using this package:
 The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/tree/main/LICENSE.md) for more information.
 
 Made with 💙
+
+## Verified local speech models
+
+Install the pinned multilingual Whisper base model before starting a private CPU speech server:
+
+```ts
+import { ensureLocalSpeechModel } from '@stacksjs/ai/local-speech-model'
+
+const modelPath = await ensureLocalSpeechModel({ directory: 'storage/speech/models' })
+```
+
+The installer checks the exact byte length and SHA-256, reuses a verified file,
+and publishes new bytes atomically. Interrupted downloads resume through a
+validated HTTP Range response. An origin that ignores Range starts a clean
+response instead. Four attempts, each with a three-minute transfer timeout, are
+the defaults; `attempts`, `timeoutMs` and an abort `signal` are configurable.
+A failed install preserves the previous target and removes only its own partial
+file. Custom trusted model metadata can be passed through `model`.

package/dist/local-speech-model.d.ts

@@ -0,0 +1,17 @@
+/** Publish a bounded, checksum-verified model atomically; callers own the models directory. */
+export declare function ensureLocalSpeechModel(options: LocalSpeechModelOptions): Promise<string>;
+/** Immutable multilingual Whisper base model used by the private CPU runtime. */
+export declare const MULTILINGUAL_BASE_SPEECH_MODEL: Readonly<LocalSpeechModel>;
+export declare interface LocalSpeechModel {
+  filename: string
+  url: string
+  sha256: string
+  bytes: number
+}
+export declare interface LocalSpeechModelOptions {
+  directory: string
+  model?: Readonly<LocalSpeechModel>
+  timeoutMs?: number
+  attempts?: number
+  signal?: AbortSignal
+}

package/dist/local-speech-model.js

@@ -0,0 +1 @@
+import{createHash,randomUUID}from"node:crypto";import{createReadStream}from"node:fs";import{mkdir,open,rename,rm,stat}from"node:fs/promises";import{join}from"node:path";export const MULTILINGUAL_BASE_SPEECH_MODEL=Object.freeze({filename:"ggml-base.bin",url:"https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-base.bin",sha256:"60ed5bc3dd14eea856493d334349b405782ddcaf0028d4b5df4088345fba2efe",bytes:147951465});async function verified(path,model){try{if((await stat(path)).size!==model.bytes)return!1}catch(error){if(error.code==="ENOENT")return!1;throw error}const hash=createHash("sha256");for await(const chunk of createReadStream(path))hash.update(chunk);return hash.digest("hex")===model.sha256.toLowerCase()}export async function ensureLocalSpeechModel(options){const model=options.model??MULTILINGUAL_BASE_SPEECH_MODEL,timeoutMs=options.timeoutMs??180000,attempts=options.attempts??4;if(!/^[a-z0-9][a-z0-9._-]*$/i.test(model.filename)||!/^[a-f0-9]{64}$/i.test(model.sha256)||!Number.isSafeInteger(model.bytes)||model.bytes<=0)throw TypeError("A speech model needs a safe filename, SHA-256 and positive byte length");if(!Number.isSafeInteger(timeoutMs)||timeoutMs<=0||timeoutMs>2147483647)throw RangeError("timeoutMs must fit the platform timer range");if(!Number.isSafeInteger(attempts)||attempts<1||attempts>10)throw RangeError("attempts must be between one and ten");options.signal?.throwIfAborted();await mkdir(options.directory,{recursive:!0,mode:448});const target=join(options.directory,model.filename);if(await verified(target,model))return target;const partial=join(options.directory,`.${model.filename}.${randomUUID()}.partial`);let failure;try{for(let attempt=0;attempt<attempts;attempt++){options.signal?.throwIfAborted();let reset=!1;try{let received=await stat(partial).then((file)=>file.size,(error)=>{if(error.code==="ENOENT")return 0;throw error});if(received===model.bytes){if(await verified(partial,model)){await rename(partial,target);return target}await rm(partial,{force:!0});received=0}const signal=options.signal?AbortSignal.any([options.signal,AbortSignal.timeout(timeoutMs)]):AbortSignal.timeout(timeoutMs),headers={"Accept-Encoding":"identity"};if(received)headers.Range=`bytes=${received}-`;const response=await fetch(model.url,{signal,headers});if(![200,206].includes(response.status)||!response.body){await response.body?.cancel();throw Error(`Speech model download failed (HTTP ${response.status})`)}if(response.status===206){const range=/^bytes (\d+)-(\d+)\/(\d+)$/.exec(response.headers.get("content-range")||"");if(!range||Number(range[1])!==received||Number(range[3])!==model.bytes||Number(range[2])<received||Number(range[2])>=model.bytes){await response.body.cancel();throw Error("Speech model response did not match the requested byte range")}}else received=0;const file=await open(partial,response.status===206?"a":"w",384),reader=response.body.getReader();try{for(;;){const{value,done}=await reader.read();if(done)break;received+=value.length;if(received>model.bytes){reset=!0;throw Error("Speech model exceeded its pinned byte length")}await file.writeFile(value)}}finally{await reader.cancel().catch(()=>{});await file.close()}if(received!==model.bytes)throw Error("Speech model response ended before its pinned byte length");if(!await verified(partial,model)){reset=!0;throw Error("Speech model did not match its pinned SHA-256")}await rename(partial,target);return target}catch(error){failure=error;options.signal?.throwIfAborted();if(reset)await rm(partial,{force:!0});if(attempt+1<attempts)await Bun.sleep(Math.min(250*2**attempt,2000))}}throw Error(`Speech model could not be verified after ${attempts} download attempts`,{cause:failure})}finally{await rm(partial,{force:!0})}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/ai",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.374",
+  "version": "0.75.377",
   "description": "Stacks Artificial Intelligence.",
   "author": "Chris Breuer",
   "contributors": [
@@ -65,11 +65,11 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/cli": "0.75.374",
-    "@stacksjs/config": "0.75.374",
-    "@stacksjs/router": "0.75.374",
-    "@stacksjs/storage": "0.75.374",
-    "@stacksjs/ts-cloud": "^0.16.69"
+    "@stacksjs/cli": "0.75.377",
+    "@stacksjs/config": "0.75.377",
+    "@stacksjs/router": "0.75.377",
+    "@stacksjs/storage": "0.75.377",
+    "@stacksjs/ts-cloud": "^0.16.89"
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.79"