quaterion: similarity learning, not quaternion rotation

The name is one letter from a maths term the project has nothing to do with

The repository is called quaterion, spelled with a single n at the end, and the package name is quaterion. Nothing in the project concerns quaternion rotation, four-dimensional representations, or any of the mathematics the spelling suggests.

The project describes itself as a framework for fine-tuning similarity learning models, from Qdrant, and the description names the problem it closes as the last mile in training models for semantic search, recommendations, anomaly detection, extreme classification and matching engines.

The tagline under the badges is a garbled quotation, described as a dwarf on a giant's shoulders seeing farther of the two. It reads as a loose rendering of the Newton line about standing on the shoulders of giants, with the grammar coming apart in the process.

So the name is doing two jobs at once. It borrows the resonance of an established technical term for a project that has nothing to do with that field, and it is short enough to type.

The practical consequence is that searching for this project by name requires care, since almost every result for the near-identical spelling is about rotations in graphics.

The last release is from March 2023 and the last push is from September 2026

The repository is not archived and its last recorded push is 2026-09-01. The release list has three entries and the newest is v0.1.35 from 2023-03-30, before that v0.1.34 from December 2022 and v0.1.33 from the week before.

The package metadata declares version 0.1.35, which matches the newest tag exactly. So the version in the manifest is not ahead of what was released, which is unusual and means you can install from an index and know which tag you are getting.

What the gap describes is a project where commits continue and releases do not. Three and a half years of commits sit above a release that most people installing today would receive from the package index.

That combination is worth reading carefully rather than as either a warning or a reassurance. Nothing in the tree says the code is broken, and the dependency constraints explain a lot on their own, since the package is pinned to an older framework generation.

The recorded popularity is 664 stars, 47 forks and 15 open issues, with the default branch named master and a documentation site on a Qdrant subdomain.

Python is capped below 3.11 and the framework is held on Lightning 1.x

The dependency list explains the release gap better than any statement of intent could.

Python is constrained to 3.8 up to but not including 3.11. That is a hard exclusion of three subsequent minor versions, and 3.8 itself is past its end of life.

The framework layer is pinned to pytorch-lightning at 1.6.4 or newer within the 1.x range. That generation of Lightning predates the 2.x rewrite by years, and the README credits that framework for the project's scalability, cost-efficiency and reliability, so the ceiling is inherited rather than chosen.

Two other dependencies carry explanatory comments that turn out to be workarounds for specific upstream bugs. Protobuf is capped below 3.20, with the comment pointing at an open Lightning issue. torchmetrics is capped at 0.8.2, with the comment saying it is capped until a warning about full_state_update is fixed.

So the constraint set is a snapshot of what worked around a particular set of upstream problems, and none of the ceilings is documented as temporary.

setuptools is pinned to one exact 2021 build, described as a temporary fix

The build-system table is the strangest corner of the manifest.

It requires poetry-core at 1.0.0 or newer and setuptools at exactly 59.5.0, and the comment beside it calls that a temporary fix and links a pull request against PyTorch. That setuptools release dates from the end of 2021.

Pinning a build tool to an exact version is normally a supply-chain measure rather than a workaround, and the two are combined here: one dependency floats and one does not, with a comment explaining that the immovable one is there because of somebody else's bug.

The dev dependency table has a matching oddity. The documentation theme is pulled from a git repository by its master branch with no reference to a commit, so a documentation build is not reproducible even though the lockfile pins the runtime.

It also uses the legacy section name for development dependencies rather than the current grouped form, which is a small sign of a manifest written against an older Poetry and not migrated.

Two packages exist so inference never installs training dependencies

The installation section is a two-line split, and the reasoning behind it is the most transferable idea in the repository.

pip install quaterion

pip install quaterion-models

The framework itself is one package, and the model classes are another, in a separate repository. The stated reason is that it is not always possible or convenient to represent a model in ONNX format, followed immediately by a parenthetical admitting that it is supported.

That parenthetical is doing honest work. If ONNX works, why keep Python model classes at all? The answer given is the one that matters: keeping a very minimal collection of model classes in a separate package avoids installing heavy training dependencies into inference infrastructure.

So the split is a deployment concern rather than a format concern. A serving box gets quaterion-models and gets a small dependency tree; a training box gets quaterion and gets the framework.

Both halves of the sentence are there for you: the full toolset for training and debugging lives in one package, and the inference-only one stays light.

Both extras declare the same dependency

The extras table has two entries and they are identical. One is named after the optional dependency itself and the other is named full, and both resolve to the same single package, pytorch-metric-learning.

That is a naming problem rather than a functional one, since neither extra pulls anything the other does not. But it means there are two ways to ask for the same thing and no way from the extras alone to tell which is the intended spelling.

The optional dependency itself is a metric learning library, and it is the natural companion to the framework's similarity objective. The advanced tutorial list includes an article on preventing vector space collapse in triplet loss, which is the problem that library addresses, so the connection is real rather than incidental.

The rest of the runtime list is short and unglamorous: torch at 1.8.2 or newer with a very loose floor, a murmurhash library, a logger, a terminal formatting library at 12.4.4 or newer, and the separate model package at 0.1.17 or newer.

The loose torch floor is the one to watch. There is no upper bound, so a resolver will happily pair a 2021 framework with a current torch and leave you to discover whether they agree.

Three runnable examples, and a cache tutorial written for laptops

The examples directory holds three worked cases, and their names tell you what the framework is aimed at.

There is a cars example, matching the documented tutorial on fine-tuning a computer vision model for similar car search. There is a cifar100 example, which is image classification over a standard benchmark. And there is a startup_search example, which is the text side, matching the tutorial on question answering systems.

The directory also carries its own gitignore and an init file, so the examples are an importable package rather than loose scripts.

The tutorial list is where the framework's claims become concrete, and four of them are about problems specific to fine-tuning rather than about generic machine learning. One is on the built-in caching mechanism and how to make training fast. One is on skip connections in head layers, framed as how to avoid forgetting while fine-tuning. One is on embedding confidence, which is phrased as the question of how to know whether the model is sure about the output vector. And one is on preventing vector space collapse in triplet loss.

Those four are the closest thing the project has to a statement of what is hard about this problem, and they are considerably more specific than the feature list.

Editorial conclusion

Use this if you are fine-tuning a pretrained encoder for semantic search or recommendation and want caching, head-layer skip connections and triplet loss collapse prevention already solved, since those four tutorials are the most specific thing the project offers. Skip it if you are on Python 3.11 or newer, because the package excludes those versions outright. Before you commit to it, note that the newest tagged release is from March 2023 while commits continue, and that the torch constraint has a lower bound and no upper bound, so what a resolver pairs with it is worth checking yourself.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. qdrant/quaterion on GitHub
4. README
5. Releases