Skip to content

Write HTML. Render video. Built for agents.

12.5 KB
Raw Blame
/**
 * 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 { 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"] ?? 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));
}