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

# Embedding

> Generate text embeddings for semantic search and similarity

# Embedding Module

Generate text embeddings with a simple API. Abstracts away the underlying provider (litellm) - users only need `praisonai.embed()` or `praisonai.embedding()`.

<Note>
  Both `embed` and `embedding` work identically - use whichever you prefer. The `embedding` alias is provided for LiteLLM naming consistency.
</Note>

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import embed  # or: from praisonai import embedding

result = embed(input="Hello world", model="text-embedding-3-small")
print(len(result.embeddings[0]))  # 1536 dimensions
```

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai[llm]
```

<Note>
  The `[llm]` extra is required for embedding support. It includes litellm for multi-provider compatibility.
</Note>

## Usage Examples

### Single Text

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import embed

result = embed(input="Hello world", model="text-embedding-3-small")
# Returns: EmbeddingResult with embeddings list
print(f"Dimensions: {len(result.embeddings[0])}")
print(f"Usage: {result.usage}")
```

### Multiple Texts

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import embed

result = embed(
    input=["Hello", "World", "PraisonAI"],
    model="text-embedding-3-small"
)
# Returns: EmbeddingResult with 3 embedding vectors
print(f"Number of embeddings: {len(result.embeddings)}")
```

### Custom Model

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import embed

# Use larger model for higher quality
result = embed(
    input="Hello world",
    model="text-embedding-3-large"
)
```

### Import Options

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Top-level imports (recommended)
from praisonai import embed
from praisonai import embedding  # alias

# Capabilities module
from praisonai.capabilities import embed, embedding

# Async versions
from praisonai.capabilities import aembed, aembedding
```

## API Reference

### `embed(input, model, **kwargs)` / `embedding(input, model, **kwargs)`

| Parameter         | Type                 | Default                    | Description                      |
| ----------------- | -------------------- | -------------------------- | -------------------------------- |
| `input`           | `str` or `List[str]` | Required                   | Text(s) to embed                 |
| `model`           | `str`                | `"text-embedding-3-small"` | Embedding model name             |
| `dimensions`      | `int`                | `None`                     | Output dimensions (if supported) |
| `encoding_format` | `str`                | `"float"`                  | "float" or "base64"              |
| `timeout`         | `float`              | `600.0`                    | Request timeout                  |
| `api_key`         | `str`                | `None`                     | API key override                 |

**Returns:** `EmbeddingResult` with:

* `embeddings`: List of embedding vectors
* `model`: Model used
* `usage`: Token usage statistics

## Supported Providers

Any provider supported by [litellm embeddings](https://docs.litellm.ai/docs/embedding/supported_embedding):

| Provider | Model Example                                      |
| -------- | -------------------------------------------------- |
| OpenAI   | `text-embedding-3-small`, `text-embedding-3-large` |
| Azure    | `azure/text-embedding-ada-002`                     |
| Cohere   | `embed-english-v3.0`                               |
| Voyage   | `voyage-02`                                        |
| Google   | `gemini/text-embedding-004`                        |
| Bedrock  | `amazon.titan-embed-text-v1`                       |

## Use Cases

### Semantic Search

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import embed

# Index documents
docs = ["AI agents are autonomous", "Machine learning is a subset of AI"]
result = embed(input=docs, model="text-embedding-3-small")
doc_embeddings = result.embeddings

# Search query
query_result = embed(input="What are AI agents?", model="text-embedding-3-small")
query_emb = query_result.embeddings[0]

# Calculate similarity (cosine)
import numpy as np
similarities = [np.dot(query_emb, doc) for doc in doc_embeddings]
```

### Duplicate Detection

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import embed

def cosine_similarity(a, b):
    return sum(x*y for x, y in zip(a, b)) / (
        sum(x**2 for x in a)**0.5 * sum(y**2 for y in b)**0.5
    )

text1 = "PraisonAI is an agent framework"
text2 = "PraisonAI provides AI agents"

emb1 = embed(input=text1, model="text-embedding-3-small").embeddings[0]
emb2 = embed(input=text2, model="text-embedding-3-small").embeddings[0]

similarity = cosine_similarity(emb1, emb2)
print(f"Similarity: {similarity:.2%}")  # ~85%
```

### RAG Pipeline

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import embed

# Store embeddings for retrieval
documents = ["Doc 1 content", "Doc 2 content", "Doc 3 content"]
result = embed(input=documents, model="text-embedding-3-small")
embeddings = result.embeddings

# Query time
query = "Find relevant docs"
query_result = embed(input=query, model="text-embedding-3-small")
query_emb = query_result.embeddings[0]

# Retrieve top-k similar documents
# ... use with vector store
```

## Performance

| Aspect           | Value                     |
| ---------------- | ------------------------- |
| Import overhead  | 0ms (lazy loaded)         |
| First call       | \~200ms (loads litellm)   |
| Subsequent calls | \~100ms                   |
| Batch efficiency | Single API call for lists |

<Tip>
  **Performance Tip:** Pass lists to `embed()` instead of calling it in a loop. This batches requests into a single API call.
</Tip>

## Error Handling

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import embed

try:
    result = embed(input="Hello", model="text-embedding-3-small")
except ImportError:
    print("Install with: pip install praisonai[llm]")
except Exception as e:
    print(f"API error: {e}")
```

## Environment Variables

| Variable         | Description                |
| ---------------- | -------------------------- |
| `OPENAI_API_KEY` | Required for OpenAI models |
| `AZURE_API_KEY`  | For Azure OpenAI           |
| `COHERE_API_KEY` | For Cohere models          |
| `GOOGLE_API_KEY` | For Gemini models          |

## Related

* [Embeddings Capability](/docs/capabilities/embeddings) - Full embeddings documentation
* [Embeddings CLI](/docs/capabilities/embeddings-cli) - CLI commands
* [Vector Store Module](/docs/sdk/praisonai/vector_store) - Store and query embeddings
* [Knowledge Module](/docs/sdk/praisonai/knowledge) - RAG with embeddings
* [Memory Module](/docs/sdk/praisonaiagents/memory/memory) - Agent memory with embeddings