|
|
--- |
|
|
license: mit |
|
|
tags: |
|
|
- aisafety |
|
|
- embeddings |
|
|
- vector-search |
|
|
- rrf |
|
|
- numerical-stability |
|
|
--- |
|
|
|
|
|
|
|
|
--- |
|
|
# Savant Engine SDK |
|
|
**Deterministic Geometric Governance for Embedding Pipelines** |
|
|
|
|
|
Savant Engine is a lightweight **Geometry Control SDK** designed to stabilize, audit, and govern vector embeddings produced by modern neural models. |
|
|
It introduces deterministic geometric guarantees without modifying model weights or semantic content. |
|
|
|
|
|
This SDK is model-agnostic and can wrap any embedding generator (Transformers, SentenceTransformers, local LLMs, or custom encoders). |
|
|
|
|
|
--- |
|
|
|
|
|
## Why Savant? |
|
|
|
|
|
Modern embedding models can silently produce vectors with near-zero norms, leading to: |
|
|
- NaN / Inf cosine similarities |
|
|
- Reciprocal Rank Fusion (RRF) collapse |
|
|
- Silent numerical corruption in production systems |
|
|
|
|
|
Savant solves this by **owning the geometry**, not the model. |
|
|
|
|
|
--- |
|
|
|
|
|
## Core Principles |
|
|
|
|
|
### 🔹 Geometry-Owned Architecture |
|
|
The embedding manifold is governed by deterministic constraints, independent of the model’s internal distribution. |
|
|
|
|
|
### 🔹 Silent Math |
|
|
Under nominal conditions, Savant introduces **zero distortion**. |
|
|
It only intervenes when geometric safety is violated. |
|
|
|
|
|
### 🔹 Auditability |
|
|
All stabilization events are logged, converting silent failures into traceable engineering signals. |
|
|
|
|
|
--- |
|
|
|
|
|
## Modules |
|
|
|
|
|
### `savant_wrapper.py` |
|
|
Core stabilization wrapper that: |
|
|
- Intercepts embedding vectors |
|
|
- Enforces a minimum geometric norm (`r_min`) |
|
|
- Logs stabilization events deterministically |
|
|
|
|
|
### `geometry_audit.py` |
|
|
Lightweight audit utilities for: |
|
|
- Recording stabilization events |
|
|
- Inspecting geometric health |
|
|
- Supporting safety-critical validation workflows |
|
|
|
|
|
### `rrf_safe_similarity.py` |
|
|
Drop-in replacements for similarity operations: |
|
|
- Safe cosine similarity |
|
|
- RRF-compatible distance calculations |
|
|
- Guaranteed finite outputs |
|
|
|
|
|
--- |
|
|
|
|
|
## Installation |
|
|
|
|
|
```bash |
|
|
pip install savant-engine |
|
|
|
|
|
Or directly from Hugging Face: |
|
|
|
|
|
pip install git+https://huggingface.co/antonypamo/savant-engine |
|
|
|
|
|
Quick Start |
|
|
from savant_wrapper import SavantWrapper |
|
|
from sentence_transformers import SentenceTransformer |
|
|
|
|
|
model = SentenceTransformer("all-MiniLM-L6-v2") |
|
|
|
|
|
savant = SavantWrapper( |
|
|
embedder=model, |
|
|
r_min=1e-4 |
|
|
) |
|
|
|
|
|
vec = savant.encode("Resonant Relational Framework") |
|
|
print(vec.shape) |
|
|
print(savant.audit_log) |
|
|
|
|
|
Design Intent |
|
|
|
|
|
Savant is not: |
|
|
|
|
|
a model |
|
|
|
|
|
a dataset |
|
|
|
|
|
a fine-tuned checkpoint |
|
|
|
|
|
Savant is: |
|
|
|
|
|
an SDK |
|
|
|
|
|
an infrastructure primitive |
|
|
|
|
|
a deterministic safety layer for AI systems |
|
|
|
|
|
Target Use Cases |
|
|
|
|
|
Reciprocal Rank Fusion (RRF) |
|
|
|
|
|
Vector databases |
|
|
|
|
|
Safety-critical AI pipelines |
|
|
|
|
|
Industrial / ISO-compliant ML systems |
|
|
|
|
|
Research validation and benchmarking |
|
|
|
|
|
License |
|
|
|
|
|
MIT License |
|
|
|
|
|
Author |
|
|
|
|
|
Antony Padilla Morales |
|
|
Costa Rica |
|
|
|
|
|
“The model generates meaning. |
|
|
Savant owns geometry.” |
