@tangleai/models 0.21.1 → 0.24.1

package/src/embed.d.ts

@@ -1,3 +1,32 @@
+/**
+ * Embeddings: the `/embeddings` wire of the same OpenAI-compatible
+ * provider family the chat client speaks, and the seam every consumer
+ * of an embedding in this package is written against —
+ *
+ *   { embed(texts, { signal }) → Promise<Float32Array[]>, model, dims }
+ *
+ * — one vector per input, in input order, from a named model at a
+ * fixed width. `model` and `dims` are a vector's identity: vectors from
+ * different models are pairwise meaningless and compare into plausible
+ * garbage, so the identity travels with every embedding and a consumer
+ * refuses to mix two. Two implementations ship here.
+ * `createEmbeddingClient` is the wire — OpenRouter, Ollama, LM Studio or
+ * any OpenAI-compatible base, resolved exactly as the chat client
+ * resolves it. `createHashEmbedder` is the deterministic reference:
+ * hashed character trigrams, dependency-free and network-free — what
+ * the tests and the offline demos run on, and demo-grade by design.
+ * Anything heavier (a local transformer runtime, a native embedding
+ * library) is the host's, wired through the same three members. This
+ * package ships no model weights, no tokenizer, no download and no
+ * opinion on which embedding model is good.
+ *
+ * The one invariant the wire client exists to own: a reply is
+ * reassembled by each item's `index`, and refused unless exactly one
+ * non-empty, finite vector of the expected width arrives per input. An
+ * embedding attached to the wrong text is worse than an error, and a
+ * client that trusts reply order gets exactly that from a provider
+ * that answers a batch out of order.
+ */
 /**
  * The OpenAI-compatible `/embeddings` client over the existing provider
  * set. The endpoint is `${base}/embeddings` from the same resolved base
@@ -11,11 +40,7 @@
  * a fixed model — is therefore reported after `attempts` tries; a probe
  * that wants a fast answer sets `retry: { attempts: 1 }`.
  *
- * @param {{ provider?: string, baseUrl?: string, apiKey?: string,
- *   model?: string, dims?: number, headers?: Record<string, string>,
- *   fetch?: typeof fetch, timeoutMs?: number,
- *   retry?: import('./retry.js').RetryOptions,
- *   cache?: import('./replay.js').ReplayCache }} [options]
+ * @param [options]
  *   - `model` is required: it is half of every vector's identity.
  *   - `cache` is the replay seam (`createChatClient` documents the
  *     contract). Here it is PER TEXT: each input is keyed by the
@@ -36,10 +61,10 @@
  *     does.
  *   - `retry` is the chat client's option, unchanged (see
  *     `createChatClient`).
- * @returns {Embedder & { provider: string }} the seam, plus the
+ * @returns the seam, plus the
  *   resolved provider name; `dims` is the settled width
  */
-export function createEmbeddingClient(options?: {
+export interface EmbeddingClientOptions {
     provider?: string;
     baseUrl?: string;
     apiKey?: string;
@@ -48,9 +73,17 @@ export function createEmbeddingClient(options?: {
     headers?: Record<string, string>;
     fetch?: typeof fetch;
     timeoutMs?: number;
-    retry?: import("./retry.js").RetryOptions;
-    cache?: import("./replay.js").ReplayCache;
+    retry?: import('./retry.ts').RetryOptions;
+    cache?: import('./replay.ts').ReplayCache;
+}
+export declare function createEmbeddingClient(options: EmbeddingClientOptions & {
+    dims: number;
 }): Embedder & {
+    dims: number;
+    provider: string;
+};
+export declare function createEmbeddingClient(options?: EmbeddingClientOptions): Omit<Embedder, 'dims'> & {
+    readonly dims: number | undefined;
     provider: string;
 };
 /**
@@ -60,13 +93,9 @@ export function createEmbeddingClient(options?: {
  * (default 5 000, as `probeProvider`). Never throws — the result object
  * is the settings-UI contract, and the live proof that a provider
  * really serves `/embeddings` beside `/chat/completions`.
- * @param {{ provider?: string, baseUrl?: string, apiKey?: string,
- *   model?: string, dims?: number, headers?: Record<string, string>,
- *   fetch?: typeof fetch, timeoutMs?: number }} [options]
- * @returns {Promise<{ ok: true, model: string, dims: number } |
- *   { ok: false, status?: number, error: string }>}
+ * @param [options]
  */
-export function probeEmbeddings(options?: {
+export declare function probeEmbeddings(options?: {
     provider?: string;
     baseUrl?: string;
     apiKey?: string;
@@ -95,35 +124,24 @@ export function probeEmbeddings(options?: {
  * thing — so it exercises retrieval mechanics (does the right memory
  * reach the prompt?) without saying anything about embedding quality,
  * which belongs to a real model behind the same seam.
- * @param {{ dims?: number }} [options] - the width (default 64); the
+ * @param [options] - the width (default 64); the
  *   identity is `hash-trigram-<dims>`, so two widths never mix
- * @returns {Embedder & { dims: number }}
  */
-export function createHashEmbedder(options?: {
+export declare function createHashEmbedder(options?: {
     dims?: number;
 }): Embedder & {
     dims: number;
 };
-/**
- * The embedder seam: what every consumer of embeddings in this package
- * takes, and what a host implements to bring its own.
- */
 export type Embedder = {
-    /**
-     *   - one vector per input, in input order; rejects `AI0001` for
-     *   anything but a non-empty array of strings
-     */
     embed: (texts: string[], options?: {
         signal?: AbortSignal;
-    }) => Promise<Float32Array[]>;
-    /**
-     * - the name half of a vector's identity
-     */
-    model: string;
-    /**
-     * - the width half; the wire client
-     * leaves it undefined until its first reply settles it, unless the
-     * caller configured it
-     */
+    }) => Promise<Float32Array<ArrayBufferLike>[]>; /**
+   * - the name half of a vector's identity
+   */
+    model: string; /**
+   * - the width half; the wire client
+   * leaves it undefined until its first reply settles it, unless the
+   * caller configured it
+   */
     dims: number | undefined;
 };