# semantica.embeddings: Supported Methods and Configuration Guide

> Explore semantica.embeddings supported methods like sentence-transformers and FastEmbed. Learn how to configure embedding strategies, pooling, and similarity metrics via env vars, config files, or the API.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: configuration-guide
- Published: 2026-08-09

---

**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`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/config.py).

## Embedding Generation Methods

The core embedding logic resides in [`semantica/embeddings/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/methods.py), which provides high-level wrappers and dispatches to concrete implementations in [`semantica/embeddings/text_embedder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/text_embedder.py) and [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/pooling_strategies.py). The `pool_embeddings` function (lines 85-87 of [`semantica/embeddings/methods.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/methods.py)) inspects the environment for optional dependencies:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/config.py) via the global `embeddings_config` instance. When `embed_text` instantiates a `TextEmbedder` (lines 78-92 of [`semantica/embeddings/methods.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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:

```python
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:

```python
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:

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

```

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

```python
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:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/methods.py) and implemented in [`semantica/embeddings/provider_stores.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/embeddings/provider_stores.py)
- Five pooling strategies (`"mean"`, `"max"`, `"cls"`, `"attention"`, `"hierarchical"`) are available via `pool_embeddings` in [`semantica/embeddings/pooling_strategies.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.