embedding-drift-lite

Compare two embedding sets and detect drift between versions.

Installation

pip install embedding-drift-lite

Usage

from embedding_drift_lite import compare_embeddings

baseline = [
    [0.10, 0.20, 0.30],
    [0.40, 0.50, 0.60],
]

current = [
    [0.11, 0.19, 0.31],
    [0.70, 0.80, 0.90],
]

report = compare_embeddings(baseline, current)
print(report)

Output

{
    "count_baseline": 2,
    "count_current": 2,
    "dimension": 3,
    "score": 85,
    "drift_detected": True,
    "metrics": {
        "mean_cosine_similarity": 0.99622,
        "mean_cosine_distance": 0.00378,
        "centroid_cosine_distance": 0.003691,
        "mean_norm_baseline": 0.81132,
        "mean_norm_current": 1.131448,
        "mean_norm_shift": 0.320128,
        "max_pairwise_cosine_distance": 0.005859,
        "compared_count": 2,
    },
    "issues": [
        {
            "type": "norm_shift",
            "severity": "medium",
            "message": "Mean embedding norm changed noticeably.",
        }
    ],
}

Load embeddings

from embedding_drift_lite import load_embeddings, compare_embeddings

baseline = load_embeddings("baseline.json")
current = load_embeddings("current.json")

report = compare_embeddings(baseline, current)
print(report)

Overview

embedding-drift-lite is a tiny Python utility for comparing embedding sets across versions.

It is useful when building:

• RAG pipelines
• vector database ingestion workflows
• embedding model migrations
• dataset versioning workflows
• AI search systems
• LLM evaluation pipelines

Features

• Compares two embedding sets
• Computes cosine drift metrics
• Computes centroid movement
• Detects norm shifts
• Supports id-aligned comparisons
• Loads embeddings from JSON
• Returns a simple drift report
• Uses the Python standard library
• Simple API

Limitations

embedding-drift-lite uses simple deterministic metrics. It is not a complete statistical monitoring system and does not replace deeper evaluation, retrieval benchmarks, human review, or production observability. Use it as one signal in your embedding quality workflow.

Issues

Report issues at: https://github.com/edujbarrios/embedding-drift-lite

Author

Eduardo J. Barrios
edujbarrios@outlook.com

License

Mozilla Public License 2.0