Anvia Docs

Import from @anvia/core or @anvia/core/embeddings.

EmbeddingModel and Embedding

type Embedding = {
  document: string;
  vector: number[];
};

interface EmbeddingModel {
  readonly dimensions?: number;
  readonly maxBatchSize?: number;
  embedTexts(texts: string[]): Promise<Embedding[]>;
}

Purpose: provider-neutral embedding contract.

Return behavior: embedTexts(...) must return one embedding per input text.

Notable errors: provider implementations may throw; helpers throw when the returned count does not match the input count.

EmbeddedDocument and Metadata

type VectorMetadataValue = string | number | boolean | null;
type VectorMetadata = Record<string, VectorMetadataValue>;

type EmbeddedDocument<T, Metadata extends VectorMetadata = VectorMetadata> = {
  id: string;
  document: T;
  metadata?: Metadata;
  embeddings: Embedding[];
};

Purpose: document plus one or more embeddings for vector stores.

Return behavior: produced by embedDocuments(...).

Notable errors: none directly.

EmbedDocumentsOptions

type EmbedDocumentsOptions<T, Metadata extends VectorMetadata = VectorMetadata> = {
  id?: (document: T, index: number) => string;
  content(document: T, index: number): string | string[];
  metadata?: (document: T, index: number) => Metadata | undefined;
  concurrency?: number;
};

Purpose: controls how typed documents become embedding inputs and metadata.

Return behavior: used by embedDocuments(...).

Notable errors: invalid content callbacks can throw and fail embedding.

Embedding Helpers

function embedText(model: EmbeddingModel, text: string): Promise<Embedding>;
function embedTexts(model: EmbeddingModel, texts: string[]): Promise<Embedding[]>;
function embedDocuments<T, Metadata extends VectorMetadata = VectorMetadata>(
  model: EmbeddingModel,
  documents: T[],
  options: EmbedDocumentsOptions<T, Metadata>,
): Promise<Array<EmbeddedDocument<T, Metadata>>>;

Purpose: normalize batching, concurrency, and count validation.

Return behavior: embedTexts([]) returns []; embedText(...) returns the first embedding from a single-item call.

Notable errors: throws when the embedding model returns no embedding or a mismatched embedding count.

Vector Math

function dotProduct(left: number[], right: number[]): number;
function cosineSimilarity(left: number[], right: number[]): number;
function angularDistance(left: number[], right: number[]): number;
function euclideanDistance(left: number[], right: number[]): number;
function manhattanDistance(left: number[], right: number[]): number;
function chebyshevDistance(left: number[], right: number[]): number;

Purpose: distance and similarity utilities for embedding vectors.

Return behavior: returns numeric scores or distances.

Notable errors: throws when vectors have different dimensions.

For workflow guidance, see Embeddings.