Skip to content

Commit 425f81a

Browse files
feat(server): voice models reuse copies already on disk
Download links a pinned model from Handy's folder or the Hugging Face cache instead of fetching it again, and Settings → Voice accepts a path to a model file or folder anywhere else. A file is linked only after its SHA-256 matches the catalog, and removing a linked model leaves the original file alone. Co-Authored-By: Claude Fable 5.2 <[email protected]>
1 parent 3cb99ce commit 425f81a

13 files changed

Lines changed: 273 additions & 4 deletions

File tree

‎apps/server/src/speech/SpeechModelStore.test.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ import * as Path from "effect/Path";
1212
import * as Stream from "effect/Stream";
1313
import { HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http";
1414

15+
import * as HostProcess from "@t3tools/shared/HostProcess";
16+
1517
import * as ServerConfig from "../config.ts";
1618
import * as SpeechModelStore from "./SpeechModelStore.ts";
1719

@@ -168,3 +170,53 @@ it.effect("cleans only download partials on cancellation or restart", () =>
168170
]);
169171
}).pipe(Effect.provide(dependencies)),
170172
);
173+
174+
it.effect("links a verified model file from another folder and never deletes it", () =>
175+
Effect.gen(function* () {
176+
const h = yield* harness;
177+
const path = yield* Path.Path;
178+
const elsewhere = yield* h.fs.makeTempDirectoryScoped({ prefix: "speech-other-app-" });
179+
const nested = path.join(elsewhere, "hub", "snapshots");
180+
yield* h.fs.makeDirectory(nested, { recursive: true });
181+
const impostor = path.join(elsewhere, "same-size.gguf");
182+
const existing = path.join(nested, "renamed-by-the-other-app.gguf");
183+
yield* h.fs.writeFile(impostor, new Uint8Array(bytes.length));
184+
yield* h.fs.writeFile(existing, bytes);
185+
186+
expect(yield* h.store.link([h.model], impostor)).toEqual([]);
187+
expect(yield* h.store.linkedFrom(h.model)).toBeUndefined();
188+
189+
expect(yield* h.store.link([h.model], elsewhere)).toEqual([h.model.id]);
190+
expect(yield* h.store.linkedFrom(h.model)).toBe(existing);
191+
expect(yield* h.store.installedPath(h.model)).toBe(h.stale);
192+
expect(h.requests).toHaveLength(0);
193+
// Pointing at T3 Code's own folder must not turn the link into a link to itself.
194+
expect(yield* h.store.link([h.model], h.directory)).toEqual([]);
195+
expect(yield* h.store.installedPath(h.model)).toBe(h.stale);
196+
197+
yield* h.store.remove(h.model);
198+
expect(yield* h.store.isReady(h.model)).toBe(false);
199+
expect([...(yield* h.fs.readFile(existing))]).toEqual([...bytes]);
200+
}).pipe(Effect.scoped, Effect.provide(dependencies)),
201+
);
202+
203+
it.effect("installs from a Hugging Face cache copy instead of downloading", () =>
204+
Effect.gen(function* () {
205+
const h = yield* harness;
206+
const path = yield* Path.Path;
207+
const home = yield* h.fs.makeTempDirectoryScoped({ prefix: "speech-home-" });
208+
const snapshot = path.join(
209+
home,
210+
".cache/huggingface/hub/models--fixture--speech-model/snapshots",
211+
h.model.revision,
212+
);
213+
yield* h.fs.makeDirectory(snapshot, { recursive: true });
214+
const cached = path.join(snapshot, h.model.filename);
215+
yield* h.fs.writeFile(cached, bytes);
216+
const store = yield* h.openStore.pipe(Effect.provideService(HostProcess.HomeDirectory, home));
217+
218+
expect(yield* store.download(h.model)).toBe(h.stale);
219+
expect(yield* store.linkedFrom(h.model)).toBe(cached);
220+
expect(h.requests).toHaveLength(0);
221+
}).pipe(Effect.scoped, Effect.provide(dependencies)),
222+
);

‎apps/server/src/speech/SpeechModelStore.ts‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,10 @@ import type { PlatformError } from "effect/PlatformError";
1414
import * as Schema from "effect/Schema";
1515
import * as Stream from "effect/Stream";
1616

17+
import * as HostProcess from "@t3tools/shared/HostProcess";
18+
1719
import * as ServerConfig from "../config.ts";
20+
import { expandHomePath } from "../os-jank.ts";
1821
import type { SpeechModel } from "./model.ts";
1922

2023
type ModelFile = Pick<SpeechModel, "id" | "filename" | "revision" | "size" | "sha256">;
@@ -44,13 +47,25 @@ export class SpeechModelStore extends Context.Service<
4447
readonly isReady: (model: ModelFile) => Effect.Effect<boolean>;
4548
/** The installed file once its SHA-256 has been verified, hashing it on first use. */
4649
readonly installedPath: (model: ModelFile) => Effect.Effect<string | undefined>;
50+
/** Links a copy the Hugging Face cache or Handy already holds; fetches only without one. */
4751
readonly download: (
4852
model: ModelFile,
4953
progress?: SpeechModelDownloadProgress,
5054
) => Effect.Effect<
5155
string,
5256
SpeechModelDownloadError | PlatformError | HttpClientError.HttpClientError
5357
>;
58+
/**
59+
* Installs catalog files already on this machine as symlinks, never copies.
60+
* `source` is a file or a folder to search; returns the ids it installed.
61+
*/
62+
readonly link: (
63+
models: ReadonlyArray<ModelFile>,
64+
source: string,
65+
) => Effect.Effect<ReadonlyArray<string>, PlatformError>;
66+
/** The outside file a linked model points at. */
67+
readonly linkedFrom: (model: ModelFile) => Effect.Effect<string | undefined>;
68+
/** Removes T3 Code's file or link; a linked file itself is left in place. */
5469
readonly remove: (model: ModelFile) => Effect.Effect<void, PlatformError>;
5570
}
5671
>()("t3/speech/SpeechModelStore") {}
@@ -59,9 +74,14 @@ const DOWNLOAD_ATTEMPTS = 3;
5974
const PARTIAL_FILENAME =
6075
/\.gguf\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.part$/i;
6176

77+
const LINK_SEARCH_DEPTH = 5;
78+
const LINK_SEARCH_ENTRIES = 5_000;
79+
6280
const make = Effect.gen(function* () {
6381
const fs = yield* FileSystem.FileSystem;
6482
const path = yield* Path.Path;
83+
const home = yield* HostProcess.HomeDirectory;
84+
const platform = yield* HostProcess.Platform;
6585
const http = yield* HttpClient.HttpClient;
6686
const random = yield* SecureRandom.SecureRandom;
6787
const config = yield* ServerConfig.ServerConfig;
@@ -73,6 +93,28 @@ const make = Effect.gen(function* () {
7393
}
7494
}
7595
const modelPath = (model: ModelFile) => path.join(directory, model.filename);
96+
const appDataDirectories =
97+
platform === "darwin"
98+
? [path.join(home, "Library", "Application Support")]
99+
: platform === "win32"
100+
? [path.join(home, "AppData", "Roaming")]
101+
: [path.join(home, ".local", "share"), path.join(home, ".config")];
102+
// Where the Hugging Face cache and Handy keep these same pinned files.
103+
const knownCopies = (model: ModelFile) => [
104+
path.join(
105+
home,
106+
".cache",
107+
"huggingface",
108+
"hub",
109+
`models--${model.id.replace("/", "--")}`,
110+
"snapshots",
111+
model.revision,
112+
model.filename,
113+
),
114+
...appDataDirectories.map((appData) =>
115+
path.join(appData, "com.pais.handy", "models", model.filename),
116+
),
117+
];
76118
// Files whose digest failed, by identity, so status polls stop calling them ready.
77119
const corrupt = new Map<string, string>();
78120

@@ -179,12 +221,64 @@ const make = Effect.gen(function* () {
179221
return downloaded;
180222
});
181223

224+
const filesUnder = Effect.fn("SpeechModelStore.filesUnder")(function* (source: string) {
225+
const files: Array<{ readonly file: string; readonly size: number }> = [];
226+
const pending = [{ entry: source, depth: LINK_SEARCH_DEPTH }];
227+
for (let visited = 0; pending.length > 0 && visited < LINK_SEARCH_ENTRIES; visited += 1) {
228+
const { entry, depth } = pending.pop()!;
229+
const info = yield* statFile(entry);
230+
if (info?.type === "File") files.push({ file: entry, size: Number(info.size) });
231+
if (info?.type !== "Directory" || depth === 0) continue;
232+
for (const name of yield* fs.readDirectory(entry).pipe(Effect.orElseSucceed(() => [])))
233+
pending.push({ entry: path.join(entry, name), depth: depth - 1 });
234+
}
235+
return files;
236+
});
237+
238+
const realPath = (file: string) => fs.realPath(file).pipe(Effect.orElseSucceed(() => undefined));
239+
240+
const link: SpeechModelStore["Service"]["link"] = Effect.fn("SpeechModelStore.link")(
241+
function* (models, source) {
242+
const root = path.resolve(
243+
yield* expandHomePath(source.trim()).pipe(
244+
Effect.provideService(Path.Path, path),
245+
Effect.provideService(HostProcess.HomeDirectory, home),
246+
),
247+
);
248+
yield* fs.makeDirectory(directory, { recursive: true });
249+
const linked: string[] = [];
250+
for (const { file, size } of yield* filesUnder(root)) {
251+
for (const model of models) {
252+
if (model.size !== size || linked.includes(model.id)) continue;
253+
const finalPath = modelPath(model);
254+
// Pointing at T3 Code's own model folder must not replace a file with a link to itself.
255+
if ((yield* realPath(file)) === (yield* realPath(finalPath))) continue;
256+
if (yield* verifiedPath(model, finalPath)) continue;
257+
if (!(yield* digestMatches(model, file))) continue;
258+
yield* fs.remove(finalPath, { force: true });
259+
// Windows grants symlinks only to privileged accounts; a hard link also shares the bytes.
260+
yield* fs.symlink(file, finalPath).pipe(Effect.catch(() => fs.link(file, finalPath)));
261+
const info = yield* fs.stat(finalPath);
262+
yield* fs
263+
.writeFileString(`${finalPath}.verified`, identity(model, info), { mode: 0o600 })
264+
.pipe(Effect.ignore);
265+
linked.push(model.id);
266+
}
267+
}
268+
return linked;
269+
},
270+
);
271+
182272
const download: SpeechModelStore["Service"]["download"] = Effect.fn("SpeechModelStore.download")(
183273
function* (model, progress = {}) {
184274
yield* Effect.annotateCurrentSpan({ modelId: model.id });
185275
const finalPath = modelPath(model);
186276
yield* fs.makeDirectory(directory, { recursive: true });
187277
if (yield* verifiedPath(model, finalPath, progress.onVerificationStart)) return finalPath;
278+
for (const copy of knownCopies(model)) {
279+
const linked = yield* link([model], copy).pipe(Effect.orElseSucceed(() => []));
280+
if (linked.length > 0) return finalPath;
281+
}
188282
const partialPath = `${finalPath}.${yield* random.uuidV4()}.part`;
189283
const url = `https://huggingface.co/${model.id}/resolve/${model.revision}/${model.filename}`;
190284
return yield* Effect.gen(function* () {
@@ -228,6 +322,10 @@ const make = Effect.gen(function* () {
228322
);
229323

230324
return SpeechModelStore.of({
325+
link,
326+
linkedFrom: Effect.fn("SpeechModelStore.linkedFrom")((model) =>
327+
fs.readLink(modelPath(model)).pipe(Effect.orElseSucceed(() => undefined)),
328+
),
231329
isReady: Effect.fn("SpeechModelStore.isReady")((model) =>
232330
expectedFile(model, modelPath(model)).pipe(
233331
Effect.map(

‎apps/server/src/speech/SpeechService.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,8 @@ const store = Layer.succeed(
103103
installedPath: (model) =>
104104
Effect.sync(() => (readyModels.has(model.id) ? "test.gguf" : undefined)),
105105
download,
106+
link: () => Effect.succeed([]),
107+
linkedFrom: () => Effect.undefined,
106108
remove: (model) =>
107109
Effect.sync(() => {
108110
readyModels.delete(model.id);

‎apps/server/src/speech/SpeechService.ts‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,8 @@ export class SpeechService extends Context.Service<
138138
readonly selectModel: (modelId: string) => Effect.Effect<SpeechModels, SpeechError>;
139139
readonly cancelDownload: (modelId: string) => Effect.Effect<SpeechModels, SpeechError>;
140140
readonly removeModel: (modelId: string) => Effect.Effect<SpeechModels, SpeechError>;
141+
/** Uses catalog model files already on this machine, from a file or folder path. */
142+
readonly linkModels: (source: string) => Effect.Effect<SpeechModels, SpeechError>;
141143
readonly prepareModel: Effect.Effect<void, SpeechError>;
142144
readonly transcribe: (
143145
pcmBytes: Uint8Array,
@@ -467,6 +469,7 @@ const make = Effect.gen(function* () {
467469
size: definition.size,
468470
supportsStreaming: definition.supportsStreaming,
469471
supportsBufferedStreaming: true,
472+
supportsModelLinking: true,
470473
supportsTranslation: definition.supportsTranslation,
471474
languages: definition.languages,
472475
supportsLanguageDetection: definition.supportsLanguageDetection,
@@ -489,8 +492,8 @@ const make = Effect.gen(function* () {
489492
const models = yield* Effect.forEach(
490493
SPEECH_MODELS,
491494
(definition) =>
492-
store.isReady(definition).pipe(
493-
Effect.map((ready): EnvironmentSpeechModel => {
495+
Effect.all([store.isReady(definition), store.linkedFrom(definition)]).pipe(
496+
Effect.map(([ready, linkedFrom]): EnvironmentSpeechModel => {
494497
const operation = downloading?.modelId === definition.id ? downloading : undefined;
495498
return {
496499
id: definition.id,
@@ -514,6 +517,7 @@ const make = Effect.gen(function* () {
514517
? "installed"
515518
: "downloadable",
516519
...(operation ? { downloaded: operation.downloaded } : {}),
520+
...(ready && linkedFrom ? { linkedFrom } : {}),
517521
};
518522
}),
519523
),
@@ -951,6 +955,21 @@ const make = Effect.gen(function* () {
951955
),
952956
),
953957
),
958+
linkModels: Effect.fn("SpeechService.linkModels")(function* (source) {
959+
yield* requireSupported;
960+
const settings = yield* readSettings("model linking");
961+
const linked = yield* exclusive(
962+
"model linking",
963+
store
964+
.link(SPEECH_MODELS, source)
965+
.pipe(Effect.mapError((cause) => speechError("model linking", cause))),
966+
);
967+
const first = linked[0];
968+
if (first === undefined) return yield* new SpeechModelNotFoundError({ modelId: source });
969+
if (!(yield* store.isReady(selectedModel(settings))))
970+
yield* writeSettings("model linking", { speechModelId: first });
971+
return yield* modelsEffect;
972+
}),
954973
updateAcceleration: Effect.fn("SpeechService.updateAcceleration")((acceleration) =>
955974
writeSettings("acceleration update", { speechAcceleration: acceleration }).pipe(
956975
Effect.andThen(freshStatus("acceleration update")),

‎apps/server/src/speech/http.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ effectIt.live("rejects oversized chunked audio without invoking transcription",
8080
prepareModel: Effect.void,
8181
models: () => Effect.succeed({ models: [] }),
8282
downloadModel: () => Effect.succeed({ models: [] }),
83+
linkModels: () => Effect.succeed({ models: [] }),
8384
selectModel: () => Effect.succeed({ models: [] }),
8485
cancelDownload: () => Effect.succeed({ models: [] }),
8586
updateAcceleration: () => Effect.succeed({ supported: false as const, reason: "test" }),
@@ -268,6 +269,7 @@ effectIt.effect.each([
268269
prepareModel: Effect.void,
269270
models: () => Effect.succeed({ models: [] }),
270271
downloadModel: () => Effect.fail(error),
272+
linkModels: () => Effect.fail(error),
271273
selectModel: () => Effect.fail(error),
272274
cancelDownload: () => Effect.fail(error),
273275
updateAcceleration: () => Effect.fail(error),

‎apps/server/src/speech/http.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,13 @@ export const speechHttpApiLayer = HttpApiBuilder.group(
164164
return yield* speech.removeModel(args.payload.modelId).pipe(mapSpeechError);
165165
}),
166166
)
167+
.handle(
168+
"linkModels",
169+
Effect.fn("environment.voice.linkModels")(function* (args) {
170+
yield* guard(args.endpoint.name, AuthSettingsWriteScope);
171+
return yield* speech.linkModels(args.payload.path).pipe(mapSpeechError);
172+
}),
173+
)
167174
.handle(
168175
"updateAcceleration",
169176
Effect.fn("environment.voice.updateAcceleration")(function* (args) {

0 commit comments

Comments
 (0)