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

# Embeddings

> Generate text embeddings using AI SDK with automatic fallback

# Agent Embeddings

PraisonAI provides embedding capabilities powered by AI SDK when available, with automatic fallback to native providers. Embeddings are useful for semantic search, memory systems, and knowledge retrieval.

## Quick Start

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant',
  llm: 'openai/gpt-4o-mini'
});

// Embed single text
const embedding = await agent.embed('Hello world');
console.log('Dimensions:', embedding.length); // 1536

// Embed multiple texts
const embeddings = await agent.embed(['Hello', 'World']);
console.log('Count:', embeddings.length); // 2
```

## Direct Embedding API

For more control, use the embedding functions directly:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { embed, embedMany, createEmbeddingProvider } from 'praisonai';

// Single embedding
const result = await embed('Hello world', {
  model: 'text-embedding-3-small',
  backend: 'ai-sdk' // or 'native' or 'auto'
});
console.log('Embedding:', result.embedding);
console.log('Tokens used:', result.usage?.tokens);

// Batch embeddings
const batchResult = await embedMany(
  ['First text', 'Second text', 'Third text'],
  { model: 'text-embedding-3-large' }
);
console.log('Embeddings:', batchResult.embeddings.length);
```

## Embedding Models

### OpenAI Models

| Model                    | Dimensions | Description                    |
| ------------------------ | ---------- | ------------------------------ |
| `text-embedding-3-small` | 1536       | Fast, cost-effective (default) |
| `text-embedding-3-large` | 3072       | Higher quality                 |
| `text-embedding-ada-002` | 1536       | Legacy model                   |

### Google Models

| Model                | Dimensions | Description      |
| -------------------- | ---------- | ---------------- |
| `text-embedding-004` | 768        | Google embedding |

### Cohere Models

| Model                     | Dimensions | Description          |
| ------------------------- | ---------- | -------------------- |
| `embed-english-v3.0`      | 1024       | English optimized    |
| `embed-multilingual-v3.0` | 1024       | Multilingual support |

## Integration with Knowledge Base

Use embeddings with the KnowledgeBase for semantic search:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, KnowledgeBase, createEmbeddingProvider } from 'praisonai';

// Create embedding provider
const embeddingProvider = createEmbeddingProvider({
  model: 'text-embedding-3-small'
});

// Create knowledge base with embeddings
const kb = new KnowledgeBase({
  embeddingProvider,
  similarityThreshold: 0.7,
  maxResults: 5
});

// Add documents
await kb.add({ id: '1', content: 'PraisonAI is an AI agent framework' });
await kb.add({ id: '2', content: 'Embeddings enable semantic search' });

// Search
const results = await kb.search('What is PraisonAI?');
console.log('Top match:', results[0].document.content);
```

## Integration with Memory

Use embeddings for semantic memory search:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Memory, createEmbeddingProvider } from 'praisonai';

const memory = new Memory({
  embeddingProvider: createEmbeddingProvider(),
  maxEntries: 1000
});

// Add memories
await memory.add('User prefers dark mode', 'user');
await memory.add('User is interested in AI', 'user');

// Semantic search
const relevant = await memory.search('What does the user like?');
```

## Backend Selection

PraisonAI automatically selects the best backend:

1. **AI SDK** (preferred): When `ai` package is installed
2. **Native**: Falls back to direct OpenAI client

### Force Backend

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Force AI SDK
const result = await embed('Hello', { backend: 'ai-sdk' });

// Force native OpenAI
const result = await embed('Hello', { backend: 'native' });

// Auto-select (default)
const result = await embed('Hello', { backend: 'auto' });
```

### Environment Variable

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Force backend globally
export PRAISONAI_BACKEND=ai-sdk  # or 'native' or 'auto'
```

## Similarity Functions

Built-in similarity functions for comparing embeddings:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { cosineSimilarity, euclideanDistance } from 'praisonai';

const emb1 = await embed('Hello');
const emb2 = await embed('Hi there');

// Cosine similarity (0-1, higher = more similar)
const similarity = cosineSimilarity(emb1.embedding, emb2.embedding);
console.log('Similarity:', similarity); // ~0.9

// Euclidean distance (lower = more similar)
const distance = euclideanDistance(emb1.embedding, emb2.embedding);
console.log('Distance:', distance);
```

## Performance Tips

1. **Batch embeddings**: Use `embedMany` for multiple texts
2. **Cache embeddings**: Store embeddings to avoid re-computation
3. **Choose model wisely**: `text-embedding-3-small` is fast and cheap

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Efficient batch processing
const texts = documents.map(d => d.content);
const { embeddings } = await embedMany(texts);

// Store with documents
documents.forEach((doc, i) => {
  doc.embedding = embeddings[i];
});
```

## Error Handling

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
try {
  const result = await embed('Hello');
} catch (error) {
  if (error.message.includes('API key')) {
    console.error('Missing OPENAI_API_KEY');
  } else if (error.message.includes('not installed')) {
    console.error('Install AI SDK: npm install ai @ai-sdk/openai');
  }
}
```

## TypeScript Types

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import type { 
  EmbeddingOptions, 
  EmbeddingResult, 
  EmbeddingBatchResult,
  EmbeddingProvider 
} from 'praisonai';

const options: EmbeddingOptions = {
  model: 'text-embedding-3-small',
  backend: 'auto',
  maxRetries: 2
};

const result: EmbeddingResult = await embed('Hello', options);
```