Architecture

Class hierarchy

Configuration flow

Every embedder module does the same thing at import time:

config = EmbedderConfig()

...creating one throwaway EmbedderConfig instance and reading its field values as default arguments in __init__ signatures. This is a module-level default value evaluated once at import time, not a live, mutable, shared config object — changing config.batch_size after import has no effect on classes whose constructors have already bound config.batch_size as their default. Only ArabicEmbedder and OllamaEmbedder read many of their defaults this way; OpenAIEmbedder, GeminiEmbedder, MistralEmbedder, and HuggingFaceEmbedder mostly hardcode their own literal defaults instead and only import EmbedderConfig for the module-level config = EmbedderConfig() line (which, in those files, ends up largely unused).

Execution flow for encode()

While each embedder's encode() implementation differs in details (API calls vs. local model calls, retry logic, rate limiting), they share a common shape:

Caching strategy differs per class:

• BaseEmbedder.encode_with_cache() — a generic dict cache keyed by an MD5 hash of the text (_get_cache_key), available to any subclass but not called internally by any subclass's own encode() — subclasses each implement their own inline caching instead.
• OpenAIEmbedder, GeminiEmbedder — plain dict cache (self._cache), keyed by raw text (Gemini appends a task-type/dimension suffix to the key).
• MistralEmbedder — a true LRU cache using collections.OrderedDict, bounded by cache_size (evicts oldest entry via popitem(last=False)).
• HuggingFaceEmbedder — dict cache keyed by MD5 hash for long strings or the raw string for short ones (_generate_cache_key), with optional TTL expiry (cache_ttl).
• ArabicEmbedder, OllamaEmbedder — no built-in per-text embedding cache in encode(); BaseEmbedder.__init__ still creates self._cache = {} when cache_embeddings=True, but neither subclass's encode() reads or writes it.

Device / backend selection

BaseEmbedder._get_best_device() probes for hardware in this order: CUDA → Apple MPS → CPU (each via torch, falling back to "cpu" if torch isn't installed). OllamaEmbedder overrides this method to unconditionally return "local", since Ollama manages its own device placement server-side. The three hosted-API embedders inherit the default device-detection logic but the resulting self.device value has no functional effect on API calls — it's stored purely for informational/logging purposes.

What could not be determined from source

• Packaging/versioning: no setup.py/pyproject.toml/__version__ was present in the analyzed files, so package version, license, and PyPI distribution name cannot be documented.
• Tests: no test suite is present in the provided source, so behavior under edge cases is documented strictly from reading the implementation, not from verified test coverage.
• __all__ includes "EmbedderMode": embeddings/__init__.py lists "EmbedderMode" in __all__, but no class, function, or variable named EmbedderMode is defined or imported anywhere in the package. from embeddings import EmbedderMode will raise ImportError. This looks like a leftover from a removed or planned feature; see Known Issues.