API Reference

Embedders

Text embedding providers — convert documents and queries into vector representations for semantic search.

BaseEmbedder ABC

All embedding providers implement the BaseEmbedder abstract base class, guaranteeing a consistent interface regardless of the underlying model or API.

python 
from abc import ABC, abstractmethod

class BaseEmbedder(ABC):
    @abstractmethod
    def embed_batch(
        self, texts: list[str], task_type: str = "retrieval_document"
    ) -> list[list[float]]: ...

    @abstractmethod
    def embed_query(self, query: str) -> list[float]: ...

    @property
    @abstractmethod
    def dimensions(self) -> int: ...
Method / Property Signature Description
embed_batch (texts: list[str], task_type: str) -> list[list[float]] Embed a list of documents. task_type hints the model toward document vs. query semantics where supported.
embed_query (query: str) -> list[float] Embed a single query string. Uses retrieval_query task type internally where applicable.
dimensions -> int (property) Returns the output vector dimensionality for this embedder instance.

Providers

Choose an embedding provider by passing its key to the embedder= argument of RAGLibrary(). The default provider is gemini.

Key Class Install extra Model Dimensions Notes
gemini DEFAULT GeminiEmbedder cognity-ai[gemini] text-embedding-004 768 Best default; free tier available
vertex_ai VertexAIEmbedder cognity-ai[vertex-ai] text-embedding-005 768 Google Cloud; requires project
openai OpenAIEmbedder cognity-ai[openai] text-embedding-3-small 1536 Also supports text-embedding-3-large (3072)
azure_openai AzureOpenAIEmbedder cognity-ai[azure] Azure-deployed model varies Enterprise Azure environments
bedrock BedrockEmbedder cognity-ai[bedrock] amazon.titan-embed-text-v2:0 1024 AWS-native; no API key needed
cohere CohereEmbedder cognity-ai[cohere] embed-english-v3.0 1024 Also multilingual variant
sentence_transformers SentenceTransformerEmbedder cognity-ai[sentence-transformers] all-MiniLM-L6-v2 384 Fully local; no API; good offline default
ollama OllamaEmbedder cognity-ai[ollama] nomic-embed-text 768 Local Ollama server required
⚠️
Anthropic embeddings Anthropic has no native embeddings API. Selecting llm="anthropic" automatically falls back to sentence_transformers for embeddings. You can override this by specifying a separate embedder= argument.

Per-Provider Examples

Quick setup snippets for each major provider via the RAGLibrary constructor.

python 
from cognity-ai import RAGLibrary

# Gemini (default)
rag = RAGLibrary(embedder="gemini", gemini_api_key="AIza...")

# OpenAI
rag = RAGLibrary(embedder="openai", openai_api_key="sk-...")

# Fully offline (no API)
rag = RAGLibrary(embedder="sentence_transformers")

# AWS Bedrock
rag = RAGLibrary(embedder="bedrock", aws_region="us-east-1")
# Uses boto3 default credential chain (IAM role, env vars, ~/.aws/credentials)

# Ollama (local)
rag = RAGLibrary(embedder="ollama", ollama_base_url="http://localhost:11434")

Direct API Usage

You can instantiate any embedder class directly without going through RAGLibrary, useful for standalone embedding tasks or custom pipelines.

python 
from cognity_ai.embedders import GeminiEmbedder

embedder = GeminiEmbedder(api_key="AIza...")

# Embed a batch of documents
vectors = embedder.embed_batch(["Hello world", "Another text"])

# Embed a single query
query_vec = embedder.embed_query("What is RAG?")

# Inspect dimensionality
print(embedder.dimensions)  # 768
💡
Batch vs. query embeddings Always use embed_query() for user queries and embed_batch() for document ingestion. For providers that support asymmetric embeddings (Gemini, Cohere, OpenAI v3), this produces meaningfully different vectors optimised for each role, improving retrieval quality.