llama-index-embeddings-fse

Prepared, unpublished LlamaIndex integration for fse 2.0. Version 0.1.0 will be published only after fse 2.0.0 and separate maintainer approval. This package lives in integrations/llama-index-embeddings-fse/ in the fse repository.

This package depends on fse and llama-index-core only. Framework dependencies never enter fse core. This package has its own CI environment and release workflow.

Use

After an fse 2.0 build and this package are installed:

from llama_index.embeddings.fse import FseEmbedding

embeddings = FseEmbedding(model_name="minishlab/potion-base-8M", workers=1, embed_batch_size=128)
query = embeddings.get_query_embedding("hello world")
rows = embeddings.get_text_embedding_batch(["hello world", "another document"])

For an existing local model, pass encoder=your_encoder, built for example with fse.Encoder.from_arrays. No download occurs with an injected encoder.

FseEmbedding implements BaseEmbedding query, text and batch hooks, including async hooks. LlamaIndex's embed_batch_size controls calls to fse. Its num_workers controls async batch concurrency, while workers controls fse workers per call. Avoid multiplying both settings without checking your application's resource use. Callbacks, caches and node embedding use the base class behavior. The transformation identity includes the encoder fingerprint and output dtype, so ingestion caches distinguish models and precision. Saved model references and options survive process-based ingestion. Reconstruction checks the loaded fingerprint. Injected in-memory encoders support caching but cannot be pickled or reconstructed without the original encoder. Save them and use a local path for multiprocessing. Serialized dictionaries omit Hub tokens. Pickling with an explicit token is refused. Use the Hub credential store for reconstruction. LlamaIndex requires new integrations to live outside its monorepo.

Framework baseline and guides

The supported minimum for version 0.1.0 is llama-index-core==0.14.25, the current stable release checked on 2026-11-01 from PyPI. This is our tested minimum and makes no compatibility claim for older framework releases. The runtime dependency allows later versions. Recheck compatibility before publication.

The implementation follows the official integration guide.

Options and behavior

load_kwargs passes options unchanged to Encoder.from_pretrained. load_kwargs={"normalize": False} returns raw means for every supported model, including fse artifacts, Model2Vec and supported sentence-transformers models. normalize="model" (the default) preserves the model's normalization rule. For example, {"revision": "<commit>", "local_files_only": True} selects a Hub revision and offline loading after the files have been cached. Hub-only options (revision, token, cache_dir, local_files_only) are invalid for local paths. See the fse loader contract. Do not pass load_kwargs with encoder=. Configure that encoder before injection. Use the Hub credential store rather than putting tokens in application configuration.

dtype="float32" (default) or "float16" controls fse output precision. workers=None uses fse's worker policy. workers=1 requests one worker. The adapter passes text and worker validation to fse without replacing its errors. Integer embeddings are unsupported because this interface requires float vectors.

Every result converts a numpy array into Python float lists. This copies values and allocates Python objects, so it takes additional time and memory. It does not retain the array's compact float16 or float32 storage. Empty text and unknown tokens follow the loaded encoder's tokenizer rules. Async methods delegate encoding and list conversion to a thread. Loading is synchronous, so construct models before serving async requests.

Development

Use standard Python 3.13. From this package directory in the fse checkout:

uv venv --python 3.13 .venv
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_FSE=2.0.0 \
  uv pip install --python .venv/bin/python -e '../..' -e '.[test]'
.venv/bin/python -m pytest -m 'not network'
.venv/bin/python -m pytest -m network
uv build --out-dir dist
.venv/bin/python examples/retrieval.py

The version override labels the development checkout for dependency resolution. It does not create a tag, release or published package.

The declared requirement is fse>=2.0.0. The version override tests the local unreleased checkout without weakening the published dependency. The network test downloads minishlab/potion-base-8M. Offline tests build a tiny local encoder with Encoder.from_arrays and compare vectors with fse directly. Tests disable Python network sockets by default and enable them for the marked network test. No model upload or paid service is needed.

CI and release

The isolated CI job tests Python 3.11 with the minimum framework and Python 3.13 with the latest framework. Network tests and the real-model retrieval example run only when requested locally. See release setup for the package tag, approval environment and pending PyPI publisher.

AI assistance

These package sources, tests and documentation were prepared with AI assistance using Codex. Validation uses offline vector parity, framework API tests and the real-model retrieval example. The maintainer remains responsible for review and maintenance. Publication and framework listing submissions require a separate maintainer decision.