Metadata-Version: 2.4
Name: embedding-drift-lite
Version: 0.1.0
Summary: Compare two embedding sets and detect drift between versions.
Project-URL: Repository, https://github.com/edujbarrios/embedding-drift-lite
Project-URL: Issues, https://github.com/edujbarrios/embedding-drift-lite/issues
Author-email: "Eduardo J. Barrios" <edujbarrios@outlook.com>
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: drift,embeddings,evaluation,rag,vectors
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# embedding-drift-lite

Compare two embedding sets and detect drift between versions.

[![PyPI](https://img.shields.io/pypi/v/embedding-drift-lite)](https://pypi.org/project/embedding-drift-lite/)
![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)

## Installation

```bash
pip install embedding-drift-lite
```

## Usage

```python
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

```python
{
    "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

```python
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
