Embeddings

Overview

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

With the introduction of the EmbeddingManager, this module supports robust lifecycle management, connection pooling, and transparent resilience patterns.

Key Features

• Domain Isolation: Uses a dedicated [ai.embeddings] configuration group, cleanly separating vectorization workloads from text generation (LLMs).
• Unified Management: The EmbeddingManager handles the initialization and reuse of embedding providers dynamically.
• Resilient Routing: Supports transparent decorator wrappers (e.g., router) to automatically fallback to secondary providers if the primary connection fails, ensuring high availability for vectorization tasks.
• Asymmetric Support: Supports models that differentiate between query and document embeddings (e.g., Vertex AI Gecko).

---

Usage Example

from nala.athomic.ai.embeddings.manager import embedding_manager

async def get_vector(text: str):
    # 1. Get a client by name (defined in settings)
    # The manager handles initialization, caching, and applies any configured wrappers (like fallbacks).
    model = embedding_manager.get_client("text_embedding_primary")

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

---

Configuration

Embeddings are configured in settings.toml under the [ai.embeddings] section. You can define multiple connections and configure resilient fallback chains using wrappers.

[default.ai.embeddings]
enabled = true
# Default connection specifically for Embeddings
default_connection_name = "text_embedding_primary"

  # 1. Primary Connection (with Router Wrapper)
  [default.ai.embeddings.connections.text_embedding_primary]
  enabled = true
  backend = "openai"
  default_model = "text-embedding-3-small"
  timeout = 5.0

    [default.ai.embeddings.connections.text_embedding_primary.provider]
    api_key = "..."

    # Automatically fallback to 'fallback_embedding' if this fails
    [[default.ai.embeddings.connections.text_embedding_primary.wrappers]]
    name = "router"
    enabled = true
    fallback_chain = ["fallback_embedding"]
    strategy = "tier"

  # 2. Fallback Connection (e.g., Local Ollama)
  [default.ai.embeddings.connections.fallback_embedding]
  enabled = true
  backend = "openai"
  default_model = "nomic-embed-text"
  timeout = 30.0

    [default.ai.embeddings.connections.fallback_embedding.provider]
    base_url = "http://localhost:11434/v1"
    api_key = "ollama" # pragma: allowlist secret

---

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 uses the ai.embeddings configuration pool to resolve active node declarations.

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 and binds the factory dependencies.

Parameters:

Name	Type	Description	Default
settings	Optional[Any]	The root embeddings settings object. If None, loads dynamically from the global application settings.	None

nala.athomic.ai.embeddings.factory.EmbeddingFactory

Bases: FactoryProtocol[EmbeddingModelProtocol, EmbeddingConnectionSettings]

Factory responsible for constructing Embedding providers and transparently applying configured decorator wrappers.

Adheres to the Open/Closed Principle by utilizing registries to resolve both base providers and decorator layers dynamically. It delegates the iteration of configured wrappers to a dedicated internal method, maintaining high cohesion.

create(settings, **kwargs) classmethod

Builds the base Embedding client and delegates the application of enabled wrappers.

Parameters:

Name	Type	Description	Default
settings	EmbeddingConnectionSettings	The configuration object for the connection.	required
**kwargs	Any	Additional unbound dependencies (such as managers or routers) to be passively injected into the custom wrapper creators.	{}

Returns:

Name	Type	Description
EmbeddingModelProtocol	EmbeddingModelProtocol	The fully composed Embedding client instance.

Raises:

Type	Description
ValueError	If the required base provider 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.