Documentation menuJavaScript API

JavaScript API

loadIndex, Cosine, buildIndex and the helpers.

Browser

`loadIndex(url, options?)`

Loads cosine-index.json and the vector file next to it and returns a Cosine instance.

Option	Default
`loadModel`	`lazy`	`lazy` loads the model on `warmup()` or the first search (not when the browser asks to save data), `eager` right away, `never` not at all
`embedder`	from the index	Your own `Embedder`, or `false` for keyword search only
`minSimilarity`	from the index	Drop semantic hits below this cosine similarity
`fetch`	`globalThis.fetch`	Custom fetch

`Cosine`

Member
`search(query, options?)`	`Promise<SearchResult[]>`. `mode`: `hybrid` (default; keyword results until the model is ready, does not wait), `lexical`, `semantic` (waits for the model). `limit` (8), `groupByPage` (false)
`searchLexical(query, options?)`	Synchronous keyword search
`warmup()`	Loads the model. Never rejects; on failure `status` becomes `model-failed`
`status`	`lexical`, `loading-model`, `ready`, `model-failed`
`onStatus(listener)`	Subscribe to status changes, returns an unsubscribe function
`chunks`	All chunks of the index

`SearchResult`

interface SearchResult {
  chunk: { id: number; doc: string; url: string; title: string; headings: string[]; text: string };
  score: number;
  matchedBy: Array<"lexical" | "semantic">;
  snippet: string;
  highlights: Array<[start: number, end: number]>; // ranges in snippet
}

highlightParts(snippet, highlights) splits a snippet into { text, match } parts for rendering.

Build (Node and browser)

Function
`buildIndex(documents, options)`	Chunks and embeds `{ id, url, title, content }` documents. Returns `{ manifest, vectors }`
`transformersEmbedder(options)`	Embedder on top of transformers.js. `model` (`english`, `multilingual` or an id), `dtype` (`q8`), `device`, `queryPrefix`, `passagePrefix`, `load`, `onProgress`
`chunkMarkdown(document, options)`	Splits one Markdown page into chunks
`htmlToMarkdown(html)`	Extracts the main content of an HTML page

From @sweberdev/cosine/node: readDocs(dir, options), writeIndex(index, outDir), buildDirectory(dir, outDir, options), loadIndexFile(path, options).

Custom embedder

Anything with this shape works, e.g. a call to your own embedding API at build time:

interface Embedder {
  model: string;
  embed(texts: string[], kind: "query" | "passage"): Promise<Float32Array[]>;
}