Embeddings

An embedding provider converts input into vectors used for similarity search. Pass the provider instance into your vector store, then pass the store into KnowledgeBase. The knowledge base delegates vector embedding to that store; it does not infer an embedding model from a dimension number. Use HashEmbedding for deterministic local wiring checks and a measured semantic model for real retrieval. Model availability and media support remain provider contracts.

EmbeddingProvider interface

import type { EmbeddingInput } from "@agentium/core";

interface EmbeddingProvider {
  readonly dimensions: number;
  embed(text: string): Promise<number[]>;
  embedBatch(texts: string[]): Promise<number[][]>;
  readonly supportsMultimodal?: boolean;
  embedMultimodal?(input: EmbeddingInput): Promise<number[]>;
}

Use the vector API reference for exact declarations. embedBatch() returns a vector per text input. embedMultimodal() returns one vector for its combined input.

Try a local embedder

Use an ESM TypeScript project ("type": "module" in package.json) on a supported Node version.

npm install @agentium/core@4.0.0
npm install --save-dev tsx typescript @types/node

Save as embedding.ts and run npx tsx embedding.ts:

import { HashEmbedding } from "@agentium/core";

const embedder = new HashEmbedding();
console.log((await embedder.embed("delivery policy")).length); // 256
console.log((await embedder.embedBatch(["delivery", "refund"])).length); // 2

This hashes tokens locally and makes no network calls. It verifies dimensions and batching, not semantic search quality.

OpenAI embeddings

Install openai, set OPENAI_API_KEY, and run this with an account that can use the selected embedding model:

import { OpenAIEmbedding } from "@agentium/core";

const embedder = new OpenAIEmbedding({ model: "text-embedding-3-small" });
const vector = await embedder.embed("Delivery takes three to five business days.");
console.log(vector.length); // 1536 with the default dimensions
const vectors = await embedder.embedBatch(["Delivery policy", "Refund policy"]);
console.log(vectors.length); // 2

Available models

OpenAI documents text-embedding-3-small and text-embedding-3-large, with default vector sizes 1,536 and 3,072 respectively. The adapter also retains a dimension mapping for legacy text-embedding-ada-002. Provider guidance was checked on 2026-10-04. OpenAI embedding guide. The adapter accepts apiKey, model, and dimensions. Its defaults are OPENAI_API_KEY, text-embedding-3-small, and that model’s known dimension. If you override dimensions, make the vector backend match and re-index existing documents as necessary.

Google embeddings

Install @google/genai and set GOOGLE_API_KEY. This example explicitly selects gemini-embedding-2; the v4 adapter’s constructor default is still text-embedding-004 when model is omitted.

import { GoogleEmbedding } from "@agentium/core";

const embedder = new GoogleEmbedding({ model: "gemini-embedding-2" });
console.log((await embedder.embed("Delivery policy")).length); // 3072
console.log((await embedder.embedBatch(["Delivery", "Refund"])).length); // 2

Available models

Google’s current guide describes gemini-embedding-2 for text and multimodal input and gemini-embedding-001 for text. Both default to 3,072 dimensions. Checked 2026-10-04. Google embedding guide. The adapter accepts apiKey, model, and dimensions. Its dimension lookup also includes older text-embedding-004 and embedding-001 IDs at 768; that lookup is not a guarantee those models remain available to an account. The adapter’s supportsMultimodal flag is based on a model-name prefix, so also verify the selected model’s actual provider capabilities.

Multimodal embeddings (Gemini Embedding 2)

This complete example indexes an image with a caption and searches with another image. It requires photo.jpg and query.jpg in the working directory, Google credentials, and the optional client above. It makes live embedding requests and keeps its index only in memory.

Index an image with a caption

import { GoogleEmbedding, InMemoryVectorStore, partsFromFile } from "@agentium/core";

const store = new InMemoryVectorStore(new GoogleEmbedding({ model: "gemini-embedding-2" }));
try {
  await store.initialize();
  const image = await partsFromFile("./photo.jpg");
  await store.upsert("photos", {
    id: "photo-1",
    content: "Sunset over a desert landscape",
    parts: [{ type: "text", text: "Sunset over a desert landscape" }, image],
    metadata: { source: "photo.jpg" },
  });
  const queryImage = await partsFromFile("./query.jpg");
  const hits = await store.search("photos", [queryImage], { topK: 1 });
  console.log(hits.map((hit) => ({ id: hit.id, score: hit.score, source: hit.metadata?.source })));
} finally {
  await store.close();
}

The output includes the indexed document ID and its similarity score. One indexed item is sufficient to verify plumbing, not to evaluate retrieval ranking. Add representative relevant and irrelevant images before evaluating quality.

Search by image

Pass ContentPart[] as the search query, as shown above. A plain numeric vector bypasses query embedding; a string uses text embedding. The stored document and query must use the same embedding space and dimensions.

Supported modalities

Core’s multimodal inputs use text, image, audio, and file parts. For a supported Google embedding model, the adapter converts image/audio/video/PDF parts into the provider request. partsFromFile(path, mimeType?) reads a file and returns one ContentPart; fetchAsBase64(url) fetches a remote resource and returns data and MIME type. Select trusted source files/URLs and respect the provider’s current size and media limits.

Output dimensions (Matryoshka)

Google documents reduced dimensions for its embedding models. Configure the requested dimension explicitly and keep the store consistent:

import { GoogleEmbedding } from "@agentium/core";

const compact = new GoogleEmbedding({ model: "gemini-embedding-2", dimensions: 768 });
console.log(compact.dimensions);

Dimension reduction and document/query formatting affect retrieval behavior; evaluate them with your corpus. The wrapper does not expose every provider-native task option. Follow the linked provider guide and implement additional input preparation in your application when needed.

Important: v1 and v2 vectors are NOT interchangeable

Changing the model changes the embedding space, even when vector lengths match. Re-index documents when switching model/version, dimensions, or incompatible input preparation. Keep the prior index until the replacement has passed your retrieval checks.

Limitations

Multimodal embedding returns one vector for the combined input; call separately when each item needs its own vector.
The vector adapters retain text, vectors, and metadata, not original media parts. Store useful source references in metadata.
Provider acceptance, account permissions, media limits, and live latency are not established by TypeScript compilation.
Batch behavior is adapter-specific; the Google wrapper issues per-input requests in bounded groups rather than a managed provider batch job.

Using with KnowledgeBase

This complete local program uses the same provider → vector store → knowledge-base composition as a live setup:

import { HashEmbedding, InMemoryVectorStore, KnowledgeBase } from "@agentium/core";

const embedder = new HashEmbedding();
const vectorStore = new InMemoryVectorStore(embedder);
const kb = new KnowledgeBase({ name: "policies", vectorStore });
try {
  await kb.add({ id: "delivery", content: "Delivery takes three to five business days." });
  const hits = await kb.search("delivery business days", { topK: 1 });
  console.log(hits[0]?.id); // delivery
} finally {
  await kb.close();
}

To use OpenAI or Google, replace the embedder with the corresponding configured provider and install its optional client. KnowledgeBase.close() closes its store, so coordinate ownership if multiple consumers share it. Continue with the retrieval tutorial to pass evidence into an Agent, or vector stores to choose persistence.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

EmbeddingProvider interface

Try a local embedder

OpenAI embeddings

Available models

Google embeddings

Available models

Multimodal embeddings (Gemini Embedding 2)

Index an image with a caption

Search by image

Supported modalities

Output dimensions (Matryoshka)

Important: v1 and v2 vectors are NOT interchangeable

Limitations

Using with KnowledgeBase

​EmbeddingProvider interface

​Try a local embedder

​OpenAI embeddings

​Available models

​Google embeddings

​Available models

​Multimodal embeddings (Gemini Embedding 2)

​Index an image with a caption

​Search by image

​Supported modalities

​Output dimensions (Matryoshka)

​Important: v1 and v2 vectors are NOT interchangeable

​Limitations

​Using with KnowledgeBase

EmbeddingProvider interface

Try a local embedder

OpenAI embeddings

Available models

Google embeddings

Available models

Multimodal embeddings (Gemini Embedding 2)

Index an image with a caption

Search by image

Supported modalities

Output dimensions (Matryoshka)

Important: v1 and v2 vectors are NOT interchangeable

Limitations

Using with KnowledgeBase