precession

Given a small paired sample of documents embedded by both models, precession fits a rotation into the new space and reports the retrieval quality of mapping the rest of the index.

Install

uv add precession-embed

pip install precession-embed

Import the library with import precession. The same install provides the precession command.

Example

import numpy as np
import precession

rng = np.random.default_rng(0)
source = rng.standard_normal((64, 16))
rotation, _ = np.linalg.qr(rng.standard_normal((16, 16)))
if np.linalg.det(rotation) < 0.0:
    rotation = rotation.copy()
    rotation[:, -1] *= -1.0
target = source @ rotation
ids = tuple(f"doc-{index:02d}" for index in range(64))
sample = precession.PairedSample(ids=ids, source=source, target=target)
hold_source = rng.standard_normal((40, 16))
holdout = precession.PairedSample(
    ids=tuple(f"hold-{index:02d}" for index in range(40)),
    source=hold_source,
    target=hold_source @ rotation,
)
config = precession.FitConfig()
fitted = precession.fit(sample, config)
mapped = precession.apply(holdout.source, fitted, config)
result = precession.plan(
    sample,
    holdout.ids,
    holdout.source,
    holdout,
    holdout,
    config,
)
print(result.verdict, result.kind, result.mean_residual, result.recall_at_k)
print(mapped.shape)

Verdicts

• APPLY. Holdout residual and recall both clear the configured line, so the map can be applied to the rest of the index.
• HYBRID. A stated fraction of documents, at or under the re-embed cap, need a real re-embed. The rest can use the map.
• REFUSE. The re-embed cap still leaves residual or recall short of the line. The result carries the measured residual and recall.
• INSUFFICIENT_SAMPLE. The paired sample is too small for the source dimension.

Limitations

A global rotation assumes the two models preserve pairwise geometry. A piecewise map still uses a paired sample. Residual on an unpaired document is the residual of its nearest sample neighbor. The method is Schönemann 1966 and Maystre et al. 2025.

Citations

Schönemann, Peter H. (1966). A generalized solution of the orthogonal Procrustes problem. Psychometrika 31(1), 1-10.

Maystre, Lucas, et al. (2025). When Embedding Models Meet: Procrustes Bounds and Applications. arXiv:2510.13406.