swarmauri_embedding_nmf 0.9.0.dev31

NMF Embedding for Swarmauri.

---

Swarmauri Embedding Nmf

swarmauri_embedding_nmf provides a Non-negative Matrix Factorization (NMF) implementation that converts collections of documents into dense numeric vectors. Under the hood it combines TfidfVectorizer and NMF from scikit-learn and wraps the results in Swarmauri's Vector type so the embeddings fit seamlessly into the wider ecosystem.

Installation

Choose the tool that matches your workflow:

# pip
pip install swarmauri_embedding_nmf

# Poetry
poetry add swarmauri_embedding_nmf

# uv
uv add swarmauri_embedding_nmf

Quickstart

from swarmauri_embedding_nmf import NmfEmbedding

documents = [
    "This is the first document",
    "This is the second document",
    "And this is the third one",
]

# n_components must not exceed the number of documents or unique terms
embedder = NmfEmbedding(n_components=3)

# Fit and transform the documents into Swarmauri Vector objects
vectors = embedder.fit_transform(documents)

for document, vector in zip(documents, vectors):
    print(document, vector.value)

print("Vocabulary:", embedder.extract_features())

# Transform a new document after fitting
new_vector = embedder.infer_vector("This is a new document")
print("New vector:", new_vector.value)

fit_transform and infer_vector both return Vector instances. Access the numerical data through each vector's .value attribute when interacting with other libraries or serialising results.

Persisting trained models

After training you can persist the TF-IDF vectoriser and NMF model:

embedder.save_model("nmf_embedding")
embedder.load_model("nmf_embedding")

The save_model method writes two files with _tfidf.joblib and _nmf.joblib suffixes, and load_model restores the same components for future inference sessions.

Swarmauri plugin usage

Installing this package also registers the swarmauri.embeddings.NmfEmbedding entry point. When you already depend on the swarmauri meta-package you can continue to import the embedder via the registry:

from swarmauri.embeddings.NmfEmbedding import NmfEmbedding

Want to help?

If you want to contribute to swarmauri-sdk, read up on our guidelines for contributing that will help you get started.