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().

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

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:

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

Performance

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

Related

• Embeddings Capability - Full embeddings documentation
• Embeddings CLI - CLI commands
• Vector Store Module - Store and query embeddings
• Knowledge Module - RAG with embeddings
• Memory Module - Agent memory with embeddings