Embeddings

// Documentation check: complete example
import { Connector, Embeddings, Vendor } from 'oneringai';

// Setup connector
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// Create embeddings instance
const embeddings = Embeddings.create({ connector: 'openai' });

// Embed a single text
const result = await embeddings.embed('Hello world');
console.log(result.embeddings[0].length);  // 1536
console.log(result.usage.promptTokens);    // 2

// Embed multiple texts (batch)
const batch = await embeddings.embed([
  'The quick brown fox',
  'A lazy dog sleeps',
  'Machine learning is powerful',
]);
console.log(batch.embeddings.length);  // 3

// Full dimensions (default)
const full = await embeddings.embed('Hello world');
console.log(full.embeddings[0].length);  // 1536

// Reduced dimensions — 3x smaller vectors; evaluate retrieval quality
const compact = await embeddings.embed('Hello world', { dimensions: 512 });
console.log(compact.embeddings[0].length);  // 512

// Even smaller — great for large-scale approximate search
const tiny = await embeddings.embed('Hello world', { dimensions: 128 });
console.log(tiny.embeddings[0].length);  // 128

// All embeddings from this instance use 512 dimensions
const embeddings = Embeddings.create({
  connector: 'openai',
  model: 'text-embedding-3-small',
  dimensions: 512,
});

const result = await embeddings.embed('Hello');
console.log(result.embeddings[0].length);  // 512

// Override per-call
const full = await embeddings.embed('Hello', { dimensions: 1536 });
console.log(full.embeddings[0].length);  // 1536

// text-embedding-3-small (recommended — cost-efficient, MRL)
const result = await embeddings.embed('search query', {
  model: 'text-embedding-3-small',
  dimensions: 1536,  // default, can reduce to 512 or 256
});

// text-embedding-3-large (higher quality, more dimensions)
const large = await embeddings.embed('search query', {
  model: 'text-embedding-3-large',
  dimensions: 3072,  // default, can reduce
});

Connector.create({
  name: 'google',
  vendor: Vendor.Google,
  auth: { type: 'api_key', apiKey: process.env.GOOGLE_API_KEY! },
});

const googleEmb = Embeddings.create({ connector: 'google' });

// gemini-embedding-2 is the current Google default (3072 dimensions).
const result = await googleEmb.embed('search query');
console.log(result.embeddings[0].length);  // 3072

// Task-aware text embedding with dimension reduction.
const compact = await googleEmb.embed('search query', {
  dimensions: 512,
  vendorOptions: {
    taskType: 'RETRIEVAL_QUERY',
    title: 'Product documentation query',
  },
});

// Multimodal content is exposed directly by the high-level API.
const mixed = await googleEmb.embedMultimodal([
  { type: 'text', text: 'Find assets similar to this launch brief' },
  { type: 'image', data: './campaign.png', mimeType: 'image/png' },
  { type: 'document', data: './brief.pdf', mimeType: 'application/pdf' },
], {
  dimensions: 1024,
  vendorOptions: { taskType: 'RETRIEVAL_DOCUMENT' },
});

Connector.create({
  name: 'ollama-local',
  vendor: Vendor.Ollama,
  auth: { type: 'none' },
  baseURL: 'http://localhost:11434/v1',
});

const local = Embeddings.create({ connector: 'ollama-local' });

// embeddinggemma (default) — compact multilingual model, 768 dims
const result = await local.embed('semantic search query');
console.log(result.embeddings[0].length);  // 768

// Use smaller model for constrained environments
const light = await local.embed('query', {
  model: 'qwen3-embedding:0.6b',  // ~400MB, 1024 dims
});

// Use nomic-embed-text for 768-dim vectors
const nomic = await local.embed('query', {
  model: 'nomic-embed-text',
});

import {
  getEmbeddingModelInfo,
  getEmbeddingModelsByVendor,
  getActiveEmbeddingModels,
  getEmbeddingModelsWithFeature,
  EMBEDDING_MODELS,
  Vendor,
} from 'oneringai';

// Get model information
const info = getEmbeddingModelInfo('text-embedding-3-small');
if (!info) throw new Error('Embedding model is not registered');
console.log(info.capabilities.maxDimensions);        // 1536
console.log(info.capabilities.maxTokens);            // 8191
console.log(info.capabilities.features.matryoshka);   // true
console.log(info.capabilities.features.multilingual);  // true
console.log(info.capabilities.limits.maxBatchSize);    // 2048

// List models by vendor
const ollamaModels = getEmbeddingModelsByVendor(Vendor.Ollama);
console.log(ollamaModels.map(m => m.name));
// ['embeddinggemma', 'all-minilm', 'qwen3-embedding', 'qwen3-embedding:4b', ...]

// Find MRL-capable models
const mrlModels = getEmbeddingModelsWithFeature('matryoshka');
console.log(mrlModels.map(m => `${m.name} (${m.capabilities.maxDimensions}d)`));

// Find multilingual models
const multilingualModels = getEmbeddingModelsWithFeature('multilingual');

// Use model constants for type safety
const modelName = EMBEDDING_MODELS[Vendor.OpenAI].TEXT_EMBEDDING_3_SMALL;
// 'text-embedding-3-small'

import { calculateEmbeddingCost } from 'oneringai';

// OpenAI text-embedding-3-small
const cost = calculateEmbeddingCost('text-embedding-3-small', 1_000_000);
console.log(`$${cost} per 1M tokens`);  // $0.02

// OpenAI text-embedding-3-large
const largeCost = calculateEmbeddingCost('text-embedding-3-large', 1_000_000);
console.log(`$${largeCost} per 1M tokens`);  // $0.13

// Ollama (free, returns null for no pricing)
const localCost = calculateEmbeddingCost('qwen3-embedding', 1_000_000);
console.log(localCost);  // null (free, local)

// Gemini Embedding 2 mixed-modality accounting plus the 50% batch discount.
const googleCost = calculateEmbeddingCost('gemini-embedding-2', 1_000_000, {
  images: 10,
  audioSeconds: 60,
  videoFrames: 30,
  batch: true,
});
console.log(googleCost); // 0.11725

// Embed documents at ingestion time
const docs = ['Document 1 text...', 'Document 2 text...', 'Document 3 text...'];
const docEmbeddings = await embeddings.embed(docs, { dimensions: 512 });
// Store docEmbeddings.embeddings in your vector database

// At query time, embed the query with the same model and dimensions
const queryResult = await embeddings.embed('user search query', { dimensions: 512 });
const queryVector = queryResult.embeddings[0];
// Use queryVector for vector similarity search

// Embed labeled examples and new text
const categories = await embeddings.embed([
  'sports news about football',
  'financial market analysis',
  'cooking recipe instructions',
]);

const newText = await embeddings.embed('The team scored in the final minute');
// Compare newText vector to category vectors using cosine similarity