neembed

Fine-tune pretrained sentence embedding models in non-Euclidean spaces with Geoopt.

Documentation · 日本語

Status: v0.1 is implemented and being prepared for its first public PyPI release. The API is intentionally small and may still evolve before a stable 1.0 release.

neembed is a lightweight integration layer between pretrained Sentence Transformer models and manifold-valued representations. It keeps the pretrained encoder intact, optionally projects its Euclidean output, and delegates Poincaré-ball geometry to Geoopt.

Pretrained Sentence Encoder
        ↓
Euclidean sentence embedding
        ↓
Projection head (optional)
        ↓
Tangent-space representation
        ↓
Geoopt manifold map
        ↓
Non-Euclidean embedding

Why non-Euclidean embeddings?

Hierarchical and tree-like relations can be awkward to represent in a flat Euclidean space. Hyperbolic spaces are a natural fit for rapidly expanding structures such as:

• taxonomies and concept hierarchies
• knowledge graphs
• hierarchical labels
• tree-like semantic relations

v0.1 deliberately focuses on one geometry: the Poincaré ball.

v0.1

The first release includes:

• Sentence Transformers as the pretrained encoder backend
• Poincaré-ball embeddings through Geoopt
• optional lower-dimensional tangent-space projection
• geodesic distance
• manifold-aware multiple-negatives ranking / InfoNCE-style loss
• ordinary AdamW fine-tuning
• encode() and distance() inference helpers
• save_pretrained() / from_pretrained() local persistence
• numerical-stability tests, a runnable example, and a Euclidean baseline experiment

Detailed behavior, assumptions, and API signatures live in the documentation.

Installation

After v0.1.0 is published to PyPI:

pip install neembed-geoopt

The PyPI distribution is named neembed-geoopt; the Python import package remains neembed.

For development:

git clone https://github.com/t-yamsaki/neembed.git
cd neembed
pip install -e ".[dev]"

Quick start

from neembed import (
    ManifoldSentenceTransformer,
    ManifoldMultipleNegativesRankingLoss,
    ManifoldTrainer,
)

model = ManifoldSentenceTransformer(
    "sentence-transformers/all-MiniLM-L6-v2",
    manifold="poincare",
    embedding_dim=64,
    curvature=1.0,
)

loss = ManifoldMultipleNegativesRankingLoss(
    model=model,
    temperature=0.1,
)

trainer = ManifoldTrainer(model=model, loss=loss)

train_batches = [
    (["Shiba Inu", "Siamese cat"], ["dog", "cat"]),
    (["dog", "cat"], ["mammal", "feline"]),
]

trainer.fit(train_batches, epochs=1)

embeddings = model.encode(["Shiba Inu", "dog", "mammal"])
distance = model.distance(embeddings[0], embeddings[1])
print(float(distance))

Each anchor is paired with the positive at the same batch index. Because off-diagonal candidates become in-batch negatives, avoid duplicate positives within one batch. See the Training guide for the objective and batching details.

Documentation

The full guide is hosted on Read the Docs:

• Installation
• Quick Start
• Architecture
• Training
• Inference
• Saving and Loading
• API Reference

Examples and validation

Run the end-to-end example:

python examples/train_poincare.py

• examples/train_poincare.py contains the workflow.
• experiments/README.md documents the fixed Euclidean-vs-Poincaré comparison experiment and its interpretation limits.

License

neembed is released under the MIT License. Third-party dependencies retain their own licenses.