Embedding Agent - PraisonAI

Turn text into vectors for semantic search, similarity, and RAG with the EmbeddingAgent.

from praisonaiagents import EmbeddingAgent

agent = EmbeddingAgent()

embedding = agent.embed("Hello world")
print(f"Dimension: {len(embedding)}")

EmbeddingAgent converts text into numerical vectors for semantic search, similarity matching, and RAG applications.

How It Works

Quick Start

Install

pip install praisonaiagents litellm
export OPENAI_API_KEY="your-key"

Create Agent

from praisonaiagents import EmbeddingAgent

agent = EmbeddingAgent()

Generate Embedding

embedding = agent.embed("Hello world")
print(f"Dimension: {len(embedding)}")

Methods

embed()

Generate embedding for a single text.

from praisonaiagents import EmbeddingAgent

agent = EmbeddingAgent()
embedding = agent.embed("Hello world")

print(f"Dimension: {len(embedding)}")
# Output: Dimension: 1536

str

required

Text to embed

str

Override model for this call

List[float]

Embedding vector

embed_batch()

Generate embeddings for multiple texts efficiently.

embeddings = agent.embed_batch([
    "First document",
    "Second document",
    "Third document"
])

print(f"Generated {len(embeddings)} embeddings")

List[str]

required

List of texts to embed

Batch embedding is more efficient than calling embed() multiple times.

similarity()

Calculate cosine similarity between two texts.

score = agent.similarity("Hello", "Hi there")
print(f"Similarity: {score:.2f}")
# Output: Similarity: 0.85

str

required

First text

str

required

Second text

float

Cosine similarity score (0.0 to 1.0)

find_most_similar()

Find most similar texts to a query.

results = agent.find_most_similar(
    query="What is machine learning?",
    candidates=[
        "ML is a subset of AI",
        "Python is a programming language",
        "Deep learning uses neural networks"
    ],
    top_k=2
)

for r in results:
    print(f"{r['score']:.2f}: {r['text']}")

str

required

Query text

List[str]

required

List of candidate texts

int

default:"5"

Number of results to return

Configuration

Basic
With Config
Dict Config

from praisonaiagents import EmbeddingAgent

agent = EmbeddingAgent(
    name="MyEmbedder",
    llm="text-embedding-3-large",
    verbose=True
)

from praisonaiagents import EmbeddingAgent, EmbeddingConfig

config = EmbeddingConfig(
    dimensions=1024,
    encoding_format="float"
)

agent = EmbeddingAgent(embedding=config)

agent = EmbeddingAgent(
    embedding={
        "dimensions": 512
    }
)

EmbeddingConfig Parameters

Parameter	Type	Default	Description
`dimensions`	int	`None`	Output dimensions (model-specific)
`encoding_format`	str	`"float"`	Format: `float` or `base64`
`timeout`	int	`60`	Request timeout in seconds

Supported Models

OpenAI

text-embedding-3-small (default)
text-embedding-3-large
text-embedding-ada-002

Cohere

cohere/embed-english-v3.0
cohere/embed-multilingual-v3.0

Voyage

voyage/voyage-3
voyage/voyage-3-lite

Mistral

mistral/mistral-embed

Examples

Semantic Search

from praisonaiagents import EmbeddingAgent

agent = EmbeddingAgent()

# Document corpus
documents = [
    "Python is a programming language",
    "Machine learning uses algorithms",
    "Neural networks are inspired by the brain",
    "Data science combines statistics and programming"
]

# Find relevant documents
results = agent.find_most_similar(
    query="How do computers learn?",
    candidates=documents,
    top_k=2
)

for r in results:
    print(f"Score: {r['score']:.3f} | {r['text']}")

Document Similarity Matrix

from praisonaiagents import EmbeddingAgent

agent = EmbeddingAgent()

docs = ["Doc A content", "Doc B content", "Doc C content"]
embeddings = agent.embed_batch(docs)

# Calculate pairwise similarities
for i, emb1 in enumerate(embeddings):
    for j, emb2 in enumerate(embeddings):
        if i < j:
            score = agent._cosine_similarity(emb1, emb2)
            print(f"Doc {i+1} vs Doc {j+1}: {score:.3f}")

RAG Retrieval

from praisonaiagents import EmbeddingAgent

agent = EmbeddingAgent(llm="text-embedding-3-large")

# Knowledge base
knowledge = [
    "The capital of France is Paris",
    "Python was created by Guido van Rossum",
    "The Earth orbits the Sun"
]

# User query
query = "Who created Python?"

# Find relevant context
results = agent.find_most_similar(query, knowledge, top_k=1)
context = results[0]["text"]

print(f"Retrieved: {context}")
# Output: Retrieved: Python was created by Guido van Rossum

Async Usage

import asyncio
from praisonaiagents import EmbeddingAgent

async def main():
    agent = EmbeddingAgent()
    
    # Async embedding
    embedding = await agent.aembed("Hello world")
    print(f"Dimension: {len(embedding)}")
    
    # Async batch
    embeddings = await agent.aembed_batch(["Text 1", "Text 2"])
    print(f"Generated: {len(embeddings)}")

asyncio.run(main())

Use Cases

Semantic Search

Find documents by meaning, not keywords

RAG

Retrieve relevant context for LLM prompts

Clustering

Group similar documents together

Deduplication

Find and remove duplicate content

Best Practices

Batch embeddings for throughput

Use the batch method over a loop of single embed() calls. One batched request is far cheaper and faster than many round trips for large corpora.

Keep the model consistent across a corpus

Vectors from different models aren’t comparable. Embed queries and documents with the same model, or similarity scores become meaningless.

Normalise before cosine similarity

Normalise vectors when your similarity metric assumes unit length. Skipping this skews rankings, especially across texts of very different lengths.

Pair with a vector store for RAG

The agent produces vectors; a vector database stores and searches them. Combine the two to build retrieval-augmented generation pipelines.

Rewrite queries for better retrieval in RAG pipelines.

Synthesise multiple sources into a report.

​How It Works

​Quick Start

​Methods

​Configuration

​EmbeddingConfig Parameters

​Supported Models

OpenAI

Cohere

Voyage

Mistral

​Examples

​Semantic Search

​Document Similarity Matrix

​RAG Retrieval

​Async Usage

​Use Cases

Semantic Search

RAG

Clustering

Deduplication

​Best Practices

​Related

How It Works

Quick Start

Methods

Configuration

EmbeddingConfig Parameters

Supported Models

Examples

Semantic Search

Document Similarity Matrix

RAG Retrieval

Async Usage

Use Cases

Best Practices

Related