Embeddings

Overview

The Embeddings module provides a unified interface for text-to-vector transformation services. It is the engine powering the Vector Store and Document Ingestion modules.

With the introduction of the EmbeddingManager, this module now supports robust lifecycle management and connection pooling, mirroring the architecture of the LLM module.

Key Features

• Unified Management: The EmbeddingManager handles the initialization and reuse of embedding providers.
• Shared Configuration: Reuses the [ai.connections] configuration group, allowing you to use the same provider settings (e.g., OpenAI API Key) for both Chat and Embeddings.
• Asymmetric Support: Supports models that differentiate between query and document embeddings (e.g., Vertex AI Gecko).

---

Usage Example

from nala.athomic.ai.embeddings import embedding_manager

async def get_vector(text: str):
    # 1. Get a client by name (defined in settings)
    # The manager handles initialization/caching.
    model = embedding_manager.get_client("openai_default")

    # 2. Generate vector
    vector = await model.embed_query(text)
    return vector

---

Configuration

Embeddings use the shared [ai.connections] pool. You specify which connection to use as default for embeddings in the root [ai] section.

[default.ai]
enabled = true
# Default connection for Chat/Generation
default_connection_name = "gpt4"
# Default connection specifically for Embeddings
default_embeddings_connection_name = "text_embedding_3"

  # Define the connection once
  [default.ai.connections.connections.text_embedding_3]
  backend = "openai"
  default_model = "text-embedding-3-small"

    [default.ai.connections.connections.text_embedding_3.provider]
    api_key = "..."

---

API Reference

nala.athomic.ai.embeddings.manager.EmbeddingManager

Bases: BaseManager[BaseEmbedding, LLMConnectionSettings]

A specialized lifecycle manager for Embedding Model connections.

This class orchestrates the initialization, connection, and shutdown of multiple Embedding providers. It shares the 'connections' configuration pool with LLMs, allowing efficient reuse of provider settings.

It inherits robust lifecycle management from BaseManager, ensuring that requested Embedding connections are established during startup and gracefully closed during shutdown.

__init__(settings=None)

Initializes the EmbeddingManager.

Parameters:

Name	Type	Description	Default
settings	Optional[AISettings]	The root AI settings object. If None, loads from global settings.	None

nala.athomic.ai.embeddings.factory.EmbeddingFactory

Factory for creating Embedding Model instances.

create(settings) staticmethod

Creates a configured instance of a BaseEmbedding provider.

Parameters:

Name	Type	Description	Default
settings	LLMConnectionSettings	The configuration settings for this connection.	required

Returns:

Type	Description
BaseEmbedding	An initialized instance of the embedding provider.

Raises:

Type	Description
ValueError	If the backend is not registered.

nala.athomic.ai.embeddings.protocol.EmbeddingModelProtocol

Bases: Protocol

Protocol defining the contract for text-to-vector transformation services.

embed_documents(texts, **kwargs) async

Generates embeddings for a list of documents to be stored.

Parameters:

Name	Type	Description	Default
texts	List[str]	List of strings to vectorize.	required
**kwargs	Any	Provider specific options (e.g. dimensionality).	{}

Returns:

Type	Description
List[List[float]]	A list of vectors (one per input text).

embed_query(text, **kwargs) async

Generates an embedding for a single user query. Some providers (like Vertex) optimize this differently from documents.

Parameters:

Name	Type	Description	Default
text	str	The query string.	required
**kwargs	Any	Provider specific options.	{}

Returns:

Type	Description
List[float]	A single vector list of floats.