Embedding Module
Generate text embeddings with a simple API. Abstracts away the underlying provider (litellm) - users only need praisonai.embed() or praisonai.embedding().
Both embed and embedding work identically - use whichever you prefer. The embedding alias is provided for LiteLLM naming consistency.
Quick Start
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
pip install praisonai[llm]
The [llm] extra is required for embedding support. It includes litellm for multi-provider compatibility.
Usage Examples
Single Text
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
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
from praisonai import embed
# Use larger model for higher quality
result = embed(
input="Hello world",
model="text-embedding-3-large"
)
Import Options
# 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
| 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 |
EmbeddingResult with:
embeddings: List of embedding vectorsmodel: Model usedusage: Token usage statistics
Supported Providers
Any provider supported by litellm embeddings:
| 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
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
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
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
| Aspect | Value |
|---|
| Import overhead | 0ms (lazy loaded) |
| First call | ~200ms (loads litellm) |
| Subsequent calls | ~100ms |
| Batch efficiency | Single API call for lists |
Performance Tip: Pass lists to embed() instead of calling it in a loop. This batches requests into a single API call.
Error Handling
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 |
