semantica.embeddings: Supported Methods and Configuration Guide

semantica.embeddings supports text embedding via sentence-transformers, FastEmbed, and deterministic fallback hashing, alongside five pooling strategies and two similarity metrics, all configurable through environment variables, config files, or the programmatic embeddings_config API.

The semantica.embeddings module in the semantica-agi/semantica repository provides a registry-driven architecture for generating vector representations from text. According to the source code, the system delegates to multiple provider backends—including transformer models and fast local embeddings—while exposing a unified configuration interface through the global embeddings_config instance defined in semantica/embeddings/config.py.

Embedding Generation Methods

The core embedding logic resides in semantica/embeddings/methods.py, which provides high-level wrappers and dispatches to concrete implementations in semantica/embeddings/text_embedder.py and semantica/embeddings/provider_stores.py.

High-Level Wrappers

The module exposes two primary generation wrappers:

• "default": Uses EmbeddingGenerator with auto-detection of the best available provider
• "text": Forwards directly to the embed_text function, which selects providers based on availability (see lines 44-56 of semantica/embeddings/methods.py)

Text Embedding Providers

When processing text, the system supports three concrete provider implementations:

• "sentence_transformers": Transformer-based sentence-transformers models offering state-of-the-art semantic accuracy. Implemented in semantica/embeddings/provider_stores.py.
• "fastembed": Fast, local CPU-optimized embeddings via the FastEmbed library. According to lines 86-88 in semantica/embeddings/methods.py, this defaults to the "BAAI/bge-small-en-v1.5" model if none is specified.
• "fallback": Deterministic hash-based embeddings (128-dimensional) used when no external libraries are installed, ensuring functionality in restricted environments.

Pooling Strategies

After generating token-level embeddings, semantica/embeddings applies pooling strategies defined in semantica/embeddings/pooling_strategies.py. The pool_embeddings function (lines 85-87 of semantica/embeddings/methods.py) instantiates pooling classes supporting five strategies:

• "mean": Arithmetic mean of token embeddings
• "max": Element-wise maximum across the sequence dimension
• "cls": Extraction of the CLS token (first token position)
• "attention": Softmax-weighted sum using attention scores
• "hierarchical": Two-level pooling that aggregates chunk-level means followed by a global mean

Similarity Calculations

The module provides vector comparison through calculate_similarity (lines 38-42 of semantica/embeddings/methods.py) and the underlying EmbeddingGenerator.compare_embeddings implementation:

• "cosine": Cosine similarity computed as dot-product divided by L2 norms
• "euclidean": Euclidean distance transformed to a 0-1 similarity score

Provider Availability

The check_available_providers() function (lines 48-68 of semantica/embeddings/methods.py) inspects the environment for optional dependencies:

from semantica.embeddings.methods import check_available_providers

print(check_available_providers())

# Output: {'sentence_transformers': True, 'fastembed': True, 'openai': False}

This reports whether sentence_transformers, fastembed, and openai packages are installed without importing them unnecessarily.

Configuration System

All tunable parameters are centralized in semantica/embeddings/config.py via the global embeddings_config instance. When embed_text instantiates a TextEmbedder (lines 78-92 of semantica/embeddings/methods.py), it loads method-specific defaults via embeddings_config.get_method_config("text") and merges explicit kwargs.

Environment Variables

Configuration values can be set via EMBEDDING_* prefixed variables mapped in lines 92-100 of semantica/embeddings/config.py:

• EMBEDDING_MODEL: Model identifier or path
• EMBEDDING_BATCH_SIZE: Processing batch size
• EMBEDDING_DIMENSION: Target embedding dimensionality
• EMBEDDING_NORMALIZE: Boolean flag for L2 normalization ("true" or "false")
• EMBEDDING_DEVICE: Compute device ("cpu", "cuda", etc.)

File-Based Configuration

YAML, JSON, or TOML files are parsed via _load_config_file, reading sections named embeddings: and embeddings_methods: for persistent configuration.

Programmatic API

Direct configuration uses embeddings_config.set() for global values and embeddings_config.set_method_config() for method-specific overrides:

from semantica.embeddings.config import embeddings_config

# Global settings

embeddings_config.set("batch_size", 64)

# Method-specific configuration

embeddings_config.set_method_config(
    "text",
    model_name="all-MiniLM-L6-v2",
    device="cuda",
    normalize=True,
)

Complete Usage Examples

Generate embeddings using the FastEmbed provider with default configuration:

from semantica.embeddings.methods import embed_text

emb = embed_text("The quick brown fox", method="fastembed")
print(emb.shape)  # (384,)

Switch to sentence-transformers for a specific call:

emb2 = embed_text("Another sentence", method="sentence_transformers")

Apply attention-based pooling to a batch of token embeddings:

import numpy as np
from semantica.embeddings.methods import pool_embeddings

batch = embed_text(["sent A", "sent B", "sent C"], method="fastembed")
pooled = pool_embeddings(batch, method="attention")
print(pooled.shape)  # (384,)

Compute cosine similarity between two vectors:

from semantica.embeddings.methods import calculate_similarity

sim = calculate_similarity(emb, emb2, method="cosine")
print(f"Cosine similarity: {sim:.3f}")

Summary

• semantica.embeddings supports three text embedding providers: "sentence_transformers", "fastembed", and "fallback", selected via the registry in semantica/embeddings/methods.py and implemented in semantica/embeddings/provider_stores.py
• Five pooling strategies ("mean", "max", "cls", "attention", "hierarchical") are available via pool_embeddings in semantica/embeddings/pooling_strategies.py
• Two similarity metrics ("cosine" and "euclidean") are exposed through calculate_similarity (lines 38-42)
• Configuration is centralized in semantica/embeddings/config.py and supports environment variables (EMBEDDING_*), config files, and the embeddings_config programmatic API
• Method-specific defaults are loaded via embeddings_config.get_method_config("text") and merged with runtime kwargs when TextEmbedder is instantiated

Frequently Asked Questions

What is the default embedding method in semantica.embeddings?

When calling embed_text without specifying a method, the system defaults to "fastembed" using the "BAAI/bge-small-en-v1.5" model, producing 384-dimensional vectors. This default is hardcoded in lines 86-88 of semantica/embeddings/methods.py and applies when no explicit model_name is provided in the configuration.

How do I configure GPU acceleration for embeddings?

Set the device parameter via embeddings_config.set_method_config("text", device="cuda") or export the environment variable EMBEDDING_DEVICE=cuda. The sentence-transformers provider automatically moves model weights and computation to the specified CUDA device, while FastEmbed operations remain CPU-bound regardless of device settings.

What happens if sentence-transformers and FastEmbed are not installed?

The system automatically falls back to the "fallback" method, which generates deterministic 128-dimensional hash-based embeddings as implemented in semantica/embeddings/provider_stores.py. This ensures the embed_text function remains functional in minimal environments, though with reduced semantic quality compared to transformer-based methods.

Can I register custom embedding methods with semantica.embeddings?

Yes. The module uses a registry pattern defined in semantica/embeddings/registry.py that enables custom method registration. You can extend the system by implementing a custom provider store class and registering it via the registry API, then configuring it through embeddings_config.set_method_config() with your custom method name.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}