> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Vectors and embeddings

> Public vectors and embeddings signatures and configuration in @agentium/core 4.0.0.

Import these **27 exports** from `@agentium/core`. Read the [vectors and embeddings guide](/knowledge/vector-stores) for setup and behavior, or return to the [package reference](/api-reference/core).

A `?` marks an optional field. These are declarations for lookup; run the examples in the linked guide. Follow related-type links for Agentium types and source links for imported dependency types.

## BaseVectorStore

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/base.ts)

```typescript theme={null}
export declare abstract class BaseVectorStore implements VectorStore {
    constructor(embedder?: EmbeddingProvider | undefined);
    abstract initialize(): Promise<void>;
    abstract upsert(collection: string, doc: VectorDocument): Promise<void>;
    abstract upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    abstract search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    abstract delete(collection: string, id: string): Promise<void>;
    abstract get(collection: string, id: string): Promise<VectorDocument | null>;
    abstract dropCollection(collection: string): Promise<void>;
    abstract close(): Promise<void>;
}
```

Related: [`ContentPart`](/api-reference/core/models#contentpart), [`EmbeddingProvider`](/api-reference/core/vector#embeddingprovider), [`VectorDocument`](/api-reference/core/vector#vectordocument), [`VectorSearchOptions`](/api-reference/core/vector#vectorsearchoptions), [`VectorSearchResult`](/api-reference/core/vector#vectorsearchresult), [`VectorStore`](/api-reference/core/vector#vectorstore).

## BM25Document

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/bm25.ts)

```typescript theme={null}
/**
 * Lightweight BM25 (Okapi BM25) implementation for keyword search.
 * Maintains an in-memory inverted index for fast full-text scoring.
 */
export interface BM25Document {
    id: string;
    content: string;
    metadata?: Record<string, unknown>;
}
```

## BM25Index

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/bm25.ts)

```typescript theme={null}
export declare class BM25Index {
    constructor(opts?: {
        k1?: number;
        b?: number;
    });
    get size(): number;
    add(doc: BM25Document): void;
    addBatch(docs: BM25Document[]): void;
    remove(id: string): void;
    clear(): void;
    search(query: string, opts?: {
        topK?: number;
        minScore?: number;
        filter?: Record<string, unknown>;
    }): BM25Result[];
}
```

Related: [`BM25Document`](/api-reference/core/vector#bm25document), [`BM25Result`](/api-reference/core/vector#bm25result).

## BM25Result

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/bm25.ts)

```typescript theme={null}
export interface BM25Result {
    id: string;
    content: string;
    score: number;
    metadata?: Record<string, unknown>;
}
```

## EmbeddingInput

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/types.ts)

```typescript theme={null}
/**
 * Input accepted by multimodal-capable embedding providers. Always produces one vector.
 */
export type EmbeddingInput = string | ContentPart | ContentPart[];
```

Related: [`ContentPart`](/api-reference/core/models#contentpart).

## EmbeddingProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/types.ts)

```typescript theme={null}
export interface EmbeddingProvider {
    readonly dimensions: number;
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
    /**
     * Optional: embed a single multimodal input (text + images + audio + video + PDFs).
     * Returns ONE aggregated vector. Implementations should throw if the configured model
     * does not support multimodal input.
     */
    embedMultimodal?(input: EmbeddingInput): Promise<number[]>;
    /** Whether this provider/model supports `embedMultimodal`. */
    readonly supportsMultimodal?: boolean;
}
```

Related: [`EmbeddingInput`](/api-reference/core/vector#embeddinginput).

## fetchAsBase64

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/embeddings/multimodal-utils.ts)

```typescript theme={null}
/**
 * Fetch a remote URL and return its base64 content + MIME type.
 * Uses the global `fetch` API (Node 20+).
 */
export declare function fetchAsBase64(url: string): Promise<{
    data: string;
    mimeType: string;
}>;
```

## GoogleEmbedding

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/embeddings/google.ts)

```typescript theme={null}
export declare class GoogleEmbedding implements EmbeddingProvider {
    readonly dimensions: number;
    readonly supportsMultimodal: boolean;
    constructor(config?: GoogleEmbeddingConfig);
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
    embedMultimodal(input: EmbeddingInput): Promise<number[]>;
}
```

Related: [`EmbeddingInput`](/api-reference/core/vector#embeddinginput), [`EmbeddingProvider`](/api-reference/core/vector#embeddingprovider), [`GoogleEmbeddingConfig`](/api-reference/core/vector#googleembeddingconfig).

## GoogleEmbeddingConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/embeddings/google.ts)

```typescript theme={null}
export interface GoogleEmbeddingConfig {
    apiKey?: string;
    model?: string;
    dimensions?: number;
}
```

## HashEmbedding

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/embeddings/hash.ts)

```typescript theme={null}
/**
 * Tiny local embedder (no API key). Good enough for deterministic tests and local prototypes
 * defaults. Swap in OpenAI/Google embeddings for production search quality.
 */
export declare class HashEmbedding implements EmbeddingProvider {
    readonly dimensions: number;
    constructor(dimensions?: number);
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
}
```

Related: [`EmbeddingProvider`](/api-reference/core/vector#embeddingprovider).

## InMemoryVectorStore

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/in-memory.ts)

```typescript theme={null}
export declare class InMemoryVectorStore extends BaseVectorStore {
    initialize(): Promise<void>;
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    delete(collection: string, id: string): Promise<void>;
    get(collection: string, id: string): Promise<VectorDocument | null>;
    dropCollection(collection: string): Promise<void>;
    close(): Promise<void>;
}
```

Related: [`BaseVectorStore`](/api-reference/core/vector#basevectorstore), [`ContentPart`](/api-reference/core/models#contentpart), [`VectorDocument`](/api-reference/core/vector#vectordocument), [`VectorSearchOptions`](/api-reference/core/vector#vectorsearchoptions), [`VectorSearchResult`](/api-reference/core/vector#vectorsearchresult).

## MongoDBVectorConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/mongodb.ts)

```typescript theme={null}
export interface MongoDBVectorConfig {
    uri: string;
    dbName?: string;
    /** Atlas Search index name (must be pre-created for $vectorSearch). Defaults to "vector_index". */
    indexName?: string;
}
```

## MongoDBVectorStore

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/mongodb.ts)

```typescript theme={null}
export declare class MongoDBVectorStore extends BaseVectorStore {
    constructor(config: MongoDBVectorConfig, embedder?: EmbeddingProvider);
    initialize(): Promise<void>;
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    delete(collection: string, id: string): Promise<void>;
    get(collection: string, id: string): Promise<VectorDocument | null>;
    dropCollection(collection: string): Promise<void>;
    close(): Promise<void>;
}
```

Related: [`BaseVectorStore`](/api-reference/core/vector#basevectorstore), [`ContentPart`](/api-reference/core/models#contentpart), [`EmbeddingProvider`](/api-reference/core/vector#embeddingprovider), [`MongoDBVectorConfig`](/api-reference/core/vector#mongodbvectorconfig), [`VectorDocument`](/api-reference/core/vector#vectordocument), [`VectorSearchOptions`](/api-reference/core/vector#vectorsearchoptions), [`VectorSearchResult`](/api-reference/core/vector#vectorsearchresult).

## OpenAIEmbedding

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/embeddings/openai.ts)

```typescript theme={null}
export declare class OpenAIEmbedding implements EmbeddingProvider {
    readonly dimensions: number;
    readonly supportsMultimodal = false;
    constructor(config?: OpenAIEmbeddingConfig);
    embed(text: string): Promise<number[]>;
    embedBatch(texts: string[]): Promise<number[][]>;
}
```

Related: [`EmbeddingProvider`](/api-reference/core/vector#embeddingprovider), [`OpenAIEmbeddingConfig`](/api-reference/core/vector#openaiembeddingconfig).

## OpenAIEmbeddingConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/embeddings/openai.ts)

```typescript theme={null}
export interface OpenAIEmbeddingConfig {
    apiKey?: string;
    baseURL?: string;
    model?: string;
    dimensions?: number;
}
```

## partsFromFile

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/embeddings/multimodal-utils.ts)

```typescript theme={null}
/**
 * Read a local file and return a `ContentPart` shaped for the given (or inferred) MIME type.
 * - `image/*`  -> `ImagePart`
 * - `audio/*`  -> `AudioPart`
 * - everything else (video, PDF, ...) -> `FilePart`
 */
export declare function partsFromFile(path: string, mimeType?: string): Promise<ContentPart>;
```

Related: [`ContentPart`](/api-reference/core/models#contentpart).

## PgVectorConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/pgvector.ts)

```typescript theme={null}
export interface PgVectorConfig {
    connectionString: string;
    dimensions?: number;
}
```

## PgVectorStore

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/pgvector.ts)

```typescript theme={null}
export declare class PgVectorStore extends BaseVectorStore {
    constructor(config: PgVectorConfig, embedder?: EmbeddingProvider);
    initialize(): Promise<void>;
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    delete(collection: string, id: string): Promise<void>;
    get(collection: string, id: string): Promise<VectorDocument | null>;
    dropCollection(collection: string): Promise<void>;
    close(): Promise<void>;
}
```

Related: [`BaseVectorStore`](/api-reference/core/vector#basevectorstore), [`ContentPart`](/api-reference/core/models#contentpart), [`EmbeddingProvider`](/api-reference/core/vector#embeddingprovider), [`PgVectorConfig`](/api-reference/core/vector#pgvectorconfig), [`VectorDocument`](/api-reference/core/vector#vectordocument), [`VectorSearchOptions`](/api-reference/core/vector#vectorsearchoptions), [`VectorSearchResult`](/api-reference/core/vector#vectorsearchresult).

## QdrantConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/qdrant.ts)

```typescript theme={null}
export interface QdrantConfig {
    url?: string;
    apiKey?: string;
    dimensions?: number;
    checkCompatibility?: boolean;
}
```

## QdrantVectorStore

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/qdrant.ts)

```typescript theme={null}
export declare class QdrantVectorStore extends BaseVectorStore {
    constructor(config?: QdrantConfig, embedder?: EmbeddingProvider);
    initialize(): Promise<void>;
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    delete(collection: string, id: string): Promise<void>;
    get(collection: string, id: string): Promise<VectorDocument | null>;
    dropCollection(collection: string): Promise<void>;
    close(): Promise<void>;
}
```

Related: [`BaseVectorStore`](/api-reference/core/vector#basevectorstore), [`ContentPart`](/api-reference/core/models#contentpart), [`EmbeddingProvider`](/api-reference/core/vector#embeddingprovider), [`QdrantConfig`](/api-reference/core/vector#qdrantconfig), [`VectorDocument`](/api-reference/core/vector#vectordocument), [`VectorSearchOptions`](/api-reference/core/vector#vectorsearchoptions), [`VectorSearchResult`](/api-reference/core/vector#vectorsearchresult).

## RankedItem

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/rrf.ts)

```typescript theme={null}
/**
 * Reciprocal Rank Fusion (RRF) — merges ranked result lists from different
 * retrieval methods into a single fused ranking.
 *
 * RRF score for document d = sum over all lists L of: 1 / (k + rank_L(d))
 * where k is a constant (default 60) that mitigates the impact of high
 * rankings by outlier systems.
 *
 * Reference: Cormack, Clarke & Buettcher (2009)
 */
export interface RankedItem {
    id: string;
    content: string;
    score: number;
    metadata?: Record<string, unknown>;
}
```

## reciprocalRankFusion

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/rrf.ts)

```typescript theme={null}
export declare function reciprocalRankFusion(rankedLists: RankedItem[][], options?: RRFOptions): RankedItem[];
```

Related: [`RankedItem`](/api-reference/core/vector#rankeditem), [`RRFOptions`](/api-reference/core/vector#rrfoptions).

## RRFOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/rrf.ts)

```typescript theme={null}
export interface RRFOptions {
    /** Fusion constant. Higher values dampen the effect of rank differences. Default 60. */
    k?: number;
    /** Maximum results to return. */
    topK?: number;
    /** Minimum fused score to include. */
    minScore?: number;
    /** Weight per ranked list. Defaults to equal weighting (1.0 each). */
    weights?: number[];
}
```

## VectorDocument

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/types.ts)

```typescript theme={null}
export interface VectorDocument {
    id: string;
    content: string;
    /**
     * Optional multimodal payload (text, image, audio, video, PDF). When set and non-empty,
     * the configured `EmbeddingProvider` must implement `embedMultimodal`; the parts will
     * be used for embedding instead of `content`.
     */
    parts?: ContentPart[];
    embedding?: number[];
    metadata?: Record<string, unknown>;
}
```

Related: [`ContentPart`](/api-reference/core/models#contentpart).

## VectorSearchOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/types.ts)

```typescript theme={null}
export interface VectorSearchOptions {
    topK?: number;
    filter?: Record<string, unknown>;
    minScore?: number;
    /**
     * Optional reranker. When set, the backend fetches `topK * rerankMultiplier` candidates,
     * then reranks them down to `topK` using the given reranker.
     */
    rerank?: Reranker;
    /**
     * Multiplier applied to `topK` when a reranker is configured. Defaults to 3.
     * Example: topK=10, rerankMultiplier=3 -> initial fetch of 30 candidates, reranked down to 10.
     */
    rerankMultiplier?: number;
}
```

Related: [`Reranker`](/api-reference/core/rerank#reranker).

## VectorSearchResult

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/types.ts)

```typescript theme={null}
export interface VectorSearchResult {
    id: string;
    content: string;
    score: number;
    metadata?: Record<string, unknown>;
}
```

## VectorStore

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/vector/types.ts)

```typescript theme={null}
export interface VectorStore {
    /** Initialize collections/indexes. Call once before use. */
    initialize(): Promise<void>;
    /** Upsert a single document (embedding computed if not provided). */
    upsert(collection: string, doc: VectorDocument): Promise<void>;
    /** Upsert multiple documents in batch. */
    upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
    /**
     * Similarity search by vector, text query, or multimodal `ContentPart[]` query.
     * Multimodal queries require an `EmbeddingProvider` with `embedMultimodal` support.
     */
    search(collection: string, query: number[] | string | ContentPart[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
    /** Delete a document by ID. */
    delete(collection: string, id: string): Promise<void>;
    /** Get a document by ID. */
    get(collection: string, id: string): Promise<VectorDocument | null>;
    /** Drop an entire collection. */
    dropCollection(collection: string): Promise<void>;
    /** Close connections. */
    close(): Promise<void>;
}
```

Related: [`ContentPart`](/api-reference/core/models#contentpart), [`VectorDocument`](/api-reference/core/vector#vectordocument), [`VectorSearchOptions`](/api-reference/core/vector#vectorsearchoptions), [`VectorSearchResult`](/api-reference/core/vector#vectorsearchresult).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.