mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* fix(cli): a preview's session follows HYPERFRAMES_CACHE_DIR when it is set * docs(cli): background previews follow HYPERFRAMES_CACHE_DIR * test(cli): unstub the preview test's env in a block body * test(cli): clear HYPERFRAMES_CACHE_DIR in the CLI's test home * fix(cli): registry cache, search model, catalog and catch-up follow HYPERFRAMES_CACHE_DIR * style(cli): format the media search cache test * test(cli): compare the model path against an absolute cache folder on Windows too * fix(cli): both catalog readers treat an empty HYPERFRAMES_CATALOG_ARTIFACT_DIR as unset
346 lines
13 KiB
TypeScript
346 lines
13 KiB
TypeScript
/**
|
|
* Rank the catalog by meaning, on the user's machine, for free.
|
|
*
|
|
* Sits between word matching and the hosted endpoint. Word matching cannot
|
|
* connect "make the pace feel faster" to a whip pan because they share no
|
|
* words; the hosted endpoint can, but needs an account and a network. This
|
|
* closes that gap with a 33 MB model the user opted into.
|
|
*
|
|
* The vectors here are 384-dimension and were produced by a different model
|
|
* than the hosted 3072-dimension set. The two are not comparable and are never
|
|
* mixed: a query is embedded by whichever model produced the vectors it is
|
|
* being compared against.
|
|
*/
|
|
|
|
// Vector metadata validation is intentionally defensive at this file boundary.
|
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
import { homedir } from "node:os";
|
|
import { namedCacheDir } from "@hyperframes/core/cache-dir";
|
|
import { join } from "node:path";
|
|
|
|
import { cosine, loadLocalEmbedder } from "./localEmbedder.js";
|
|
import { LOCAL_MODEL_DIMENSIONS, isLocalModelReady } from "./localModel.js";
|
|
|
|
interface LocalVectorSet {
|
|
names: string[];
|
|
dimensions: number;
|
|
vectors: Float32Array;
|
|
}
|
|
|
|
interface LocalVectorMetadata {
|
|
names: string[];
|
|
dimensions: number;
|
|
revision?: string;
|
|
rows?: MediaVectorRow[];
|
|
}
|
|
|
|
export interface MediaVectorRow {
|
|
id: string;
|
|
kind: string;
|
|
title: string;
|
|
description: string;
|
|
tags: string[];
|
|
file: string;
|
|
duration?: number;
|
|
dimensions?: { width: number; height: number };
|
|
}
|
|
|
|
export function isMediaVectorRow(value: unknown): value is MediaVectorRow {
|
|
if (!value || typeof value !== "object") return false;
|
|
const row = value as Partial<MediaVectorRow>;
|
|
return (
|
|
typeof row.id === "string" &&
|
|
typeof row.kind === "string" &&
|
|
typeof row.title === "string" &&
|
|
typeof row.description === "string" &&
|
|
Array.isArray(row.tags) &&
|
|
row.tags.every((tag) => typeof tag === "string") &&
|
|
typeof row.file === "string" &&
|
|
(row.duration === undefined ||
|
|
(typeof row.duration === "number" && Number.isFinite(row.duration) && row.duration >= 0)) &&
|
|
(row.dimensions === undefined ||
|
|
(typeof row.dimensions === "object" &&
|
|
row.dimensions !== null &&
|
|
Number.isInteger(row.dimensions.width) &&
|
|
Number.isInteger(row.dimensions.height) &&
|
|
row.dimensions.width > 0 &&
|
|
row.dimensions.height > 0))
|
|
);
|
|
}
|
|
|
|
export interface FetchLocalVectorOptions {
|
|
directory?: string;
|
|
expectedRevision?: string;
|
|
artifactBasename?: "local-vectors" | "media-vectors";
|
|
}
|
|
|
|
const CATALOG_ARTIFACT_TIMEOUT_MS = 30_000;
|
|
|
|
/** Where the bundled vector set lives, overridable for development. */
|
|
function localVectorDirectory(): string {
|
|
return (
|
|
process.env["HYPERFRAMES_CATALOG_ARTIFACT_DIR"] ||
|
|
namedCacheDir("catalog") ||
|
|
join(homedir(), ".hyperframes", "catalog")
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Put the catalog vectors in the user's cache, once.
|
|
*
|
|
* They are fetched rather than bundled: every install would otherwise carry a
|
|
* copy of a file only people who opt into offline ranking will ever read, and
|
|
* the vectors have to track the registry anyway, so shipping them inside the
|
|
* package would freeze them to the release instead.
|
|
*
|
|
* Returns false rather than throwing. A download that fails costs the offline
|
|
* tier, never the command, and the caller says so.
|
|
*/
|
|
/**
|
|
* Do a freshly fetched metadata/matrix pair describe the same index?
|
|
*
|
|
* `names.length * dimensions` floats, at four bytes each, is the whole
|
|
* contract. A pair that fails it is a truncated download or a different
|
|
* model, never something worth caching.
|
|
*/
|
|
export function vectorPairAgrees(
|
|
fetched: Array<[string, Buffer]>,
|
|
artifactBasename: "local-vectors" | "media-vectors",
|
|
): boolean {
|
|
const meta = fetched.find(([file]) => file === `${artifactBasename}.json`)?.[1];
|
|
const bin = fetched.find(([file]) => file === `${artifactBasename}.bin`)?.[1];
|
|
if (!meta || !bin) return false;
|
|
try {
|
|
const parsed = JSON.parse(meta.toString("utf-8")) as {
|
|
names?: string[];
|
|
dimensions?: number;
|
|
rows?: Array<{ id?: string }>;
|
|
};
|
|
if (parsed.dimensions !== LOCAL_MODEL_DIMENSIONS) return false;
|
|
if (
|
|
artifactBasename === "media-vectors" &&
|
|
(!parsed.rows ||
|
|
parsed.rows.length !== (parsed.names?.length ?? -1) ||
|
|
parsed.rows.some(
|
|
(row, index) => !isMediaVectorRow(row) || row.id !== parsed.names?.[index],
|
|
))
|
|
) {
|
|
return false;
|
|
}
|
|
return bin.byteLength === (parsed.names?.length ?? -1) * LOCAL_MODEL_DIMENSIONS * 4;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
/** The registry manifest and fetched pair must describe the same generation. */
|
|
function vectorRevisionAgrees(
|
|
fetched: Array<[string, Buffer]>,
|
|
expectedRevision?: string,
|
|
artifactBasename: "local-vectors" | "media-vectors" = "local-vectors",
|
|
): boolean {
|
|
if (expectedRevision === undefined) return true;
|
|
const meta = fetched.find(([file]) => file === `${artifactBasename}.json`)?.[1];
|
|
if (!meta) return false;
|
|
try {
|
|
const parsed = JSON.parse(meta.toString("utf-8")) as { revision?: unknown };
|
|
return parsed.revision === expectedRevision;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
export async function fetchLocalVectors(
|
|
registryBaseUrl: string,
|
|
options: FetchLocalVectorOptions = {},
|
|
): Promise<boolean> {
|
|
const directory = options.directory ?? localVectorDirectory();
|
|
const artifactBasename = options.artifactBasename ?? "local-vectors";
|
|
const base = registryBaseUrl.replace(/\/+$/, "");
|
|
try {
|
|
mkdirSync(directory, { recursive: true, mode: 0o700 });
|
|
// Downloaded in full before anything is written. The two files have to
|
|
// agree on how many rows there are, so a fetch that fails halfway through
|
|
// must leave the previous pair intact rather than pairing a new name list
|
|
// with an old matrix, which loads as an error instead of as stale data.
|
|
const fetched: Array<[string, Buffer]> = [];
|
|
for (const file of [`${artifactBasename}.json`, `${artifactBasename}.bin`] as const) {
|
|
const response = await fetch(`${base}/catalog-artifact/${file}`, {
|
|
signal: AbortSignal.timeout(CATALOG_ARTIFACT_TIMEOUT_MS),
|
|
});
|
|
if (!response.ok) return false;
|
|
fetched.push([file, Buffer.from(await response.arrayBuffer())]);
|
|
}
|
|
// Check the pair agrees BEFORE either file lands. Writing first and
|
|
// discovering the mismatch at load time leaves a cache that fails every
|
|
// subsequent search until someone deletes it by hand, and it is the only
|
|
// point where a truncated or wrong-model response can still be refused.
|
|
if (
|
|
!vectorPairAgrees(fetched, artifactBasename) ||
|
|
!vectorRevisionAgrees(fetched, options.expectedRevision, artifactBasename)
|
|
) {
|
|
return false;
|
|
}
|
|
// 0o600: the cache is this user's, and the directory may be world-writable
|
|
// when the caller overrides it.
|
|
for (const [file, bytes] of fetched) {
|
|
writeFileSync(join(directory, file), bytes, { mode: 0o600 });
|
|
}
|
|
return artifactBasename === "media-vectors"
|
|
? hasMediaVectors(directory)
|
|
: hasLocalVectors(directory);
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
export function hasLocalVectors(directory = localVectorDirectory()): boolean {
|
|
return (
|
|
existsSync(join(directory, "local-vectors.bin")) &&
|
|
existsSync(join(directory, "local-vectors.json"))
|
|
);
|
|
}
|
|
|
|
function hasMediaVectors(directory = localVectorDirectory()): boolean {
|
|
return (
|
|
existsSync(join(directory, "media-vectors.bin")) &&
|
|
existsSync(join(directory, "media-vectors.json"))
|
|
);
|
|
}
|
|
|
|
function loadLocalVectors(directory = localVectorDirectory()): LocalVectorSet {
|
|
const meta = JSON.parse(
|
|
readFileSync(join(directory, "local-vectors.json"), "utf-8"),
|
|
) as LocalVectorMetadata;
|
|
const buffer = readFileSync(join(directory, "local-vectors.bin"));
|
|
const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
|
|
|
|
const expected = meta.names.length * meta.dimensions;
|
|
if (vectors.length !== expected) {
|
|
throw new Error(`local vectors hold ${vectors.length} floats, expected ${expected}`);
|
|
}
|
|
if (meta.dimensions !== LOCAL_MODEL_DIMENSIONS) {
|
|
// A dimension mismatch means the vectors and the model disagree, which
|
|
// produces confident nonsense rather than an error.
|
|
throw new Error(
|
|
`local vectors are ${meta.dimensions}-dimension, model produces ${LOCAL_MODEL_DIMENSIONS}`,
|
|
);
|
|
}
|
|
return { names: meta.names, dimensions: meta.dimensions, vectors };
|
|
}
|
|
|
|
function loadMediaVectors(directory = localVectorDirectory()): LocalVectorSet & {
|
|
rows: MediaVectorRow[];
|
|
} {
|
|
const meta = JSON.parse(
|
|
readFileSync(join(directory, "media-vectors.json"), "utf-8"),
|
|
) as LocalVectorMetadata;
|
|
const buffer = readFileSync(join(directory, "media-vectors.bin"));
|
|
const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
|
|
const rows = meta.rows ?? [];
|
|
if (rows.length !== meta.names.length) {
|
|
throw new Error(`media vectors hold ${rows.length} rows, expected ${meta.names.length}`);
|
|
}
|
|
if (rows.some((row, index) => !isMediaVectorRow(row) || row.id !== meta.names[index])) {
|
|
throw new Error("media vector row order does not match media vector names");
|
|
}
|
|
if (vectors.length !== rows.length * meta.dimensions) {
|
|
throw new Error(
|
|
`media vectors hold ${vectors.length} floats, expected ${rows.length * meta.dimensions}`,
|
|
);
|
|
}
|
|
if (meta.dimensions !== LOCAL_MODEL_DIMENSIONS) {
|
|
throw new Error(
|
|
`media vectors are ${meta.dimensions}-dimension, model produces ${LOCAL_MODEL_DIMENSIONS}`,
|
|
);
|
|
}
|
|
return { names: meta.names, dimensions: meta.dimensions, vectors, rows };
|
|
}
|
|
|
|
/**
|
|
* The names the on-device index holds, without loading the vector matrix.
|
|
*
|
|
* Callers compare this against the live registry to see what meaning search
|
|
* cannot reach. Reads the metadata file only, so it costs a small JSON parse
|
|
* rather than the whole matrix, and answers empty rather than throwing: an
|
|
* absent or unreadable artifact covers nothing, which is a coverage answer
|
|
* rather than a reason to fail the search that asked.
|
|
*/
|
|
export function localVectorNames(directory = localVectorDirectory()): string[] {
|
|
if (!hasLocalVectors(directory)) return [];
|
|
try {
|
|
const meta = JSON.parse(readFileSync(join(directory, "local-vectors.json"), "utf-8")) as {
|
|
names?: string[];
|
|
};
|
|
return meta.names ?? [];
|
|
} catch {
|
|
return [];
|
|
}
|
|
}
|
|
|
|
/** Revision of the last complete pair, absent for pre-revision and unreadable caches. */
|
|
export function cachedLocalVectorRevision(directory = localVectorDirectory()): string | undefined {
|
|
if (!hasLocalVectors(directory)) return undefined;
|
|
try {
|
|
const meta = JSON.parse(readFileSync(join(directory, "local-vectors.json"), "utf-8")) as {
|
|
revision?: unknown;
|
|
};
|
|
return typeof meta.revision === "string" ? meta.revision : undefined;
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Names ranked best first, each with the similarity that placed it there.
|
|
* Returns null when local semantic search is not available.
|
|
*
|
|
* The score rides along because this ranker has no relevance threshold: every
|
|
* query returns the whole set in some order, so a caller holding names alone
|
|
* cannot tell a real match from the least-bad row of a query that matched
|
|
* nothing at all.
|
|
*/
|
|
export async function localSemanticRanking(
|
|
query: string,
|
|
directory = localVectorDirectory(),
|
|
): Promise<Array<{ name: string; score: number }> | null> {
|
|
if (!isLocalModelReady() || !hasLocalVectors(directory)) return null;
|
|
|
|
const set = loadLocalVectors(directory);
|
|
const embedder = await loadLocalEmbedder();
|
|
const [queryVector] = await embedder.embed([query], { isQuery: true });
|
|
if (!queryVector) return null;
|
|
|
|
const scored = set.names.map((name, row) => {
|
|
const start = row * set.dimensions;
|
|
return {
|
|
name,
|
|
score: cosine(queryVector, Array.from(set.vectors.subarray(start, start + set.dimensions))),
|
|
};
|
|
});
|
|
|
|
// Ties break on descending name, matching every other ranking in this system.
|
|
scored.sort((a, b) => b.score - a.score || b.name.localeCompare(a.name));
|
|
return scored;
|
|
}
|
|
|
|
export async function mediaSemanticRanking(
|
|
query: string,
|
|
directory = localVectorDirectory(),
|
|
): Promise<Array<{ row: MediaVectorRow; score: number }> | null> {
|
|
if (!isLocalModelReady() || !hasMediaVectors(directory)) return null;
|
|
const set = loadMediaVectors(directory);
|
|
const embedder = await loadLocalEmbedder();
|
|
const [queryVector] = await embedder.embed([query], { isQuery: true });
|
|
if (!queryVector) return null;
|
|
return set.rows
|
|
.map((row, index) => ({
|
|
row,
|
|
score: cosine(
|
|
queryVector,
|
|
Array.from(set.vectors.subarray(index * set.dimensions, (index + 1) * set.dimensions)),
|
|
),
|
|
}))
|
|
.sort((a, b) => b.score - a.score || b.row.id.localeCompare(a.row.id));
|
|
}
|