Hugging Face's logo

antonypamo
/
savant-engine

aisafety
embeddings
vector-search
rrf
numerical-stability
Model card Files
xet
Community
savant-engine
File size: 2,789 Bytes
a55b0ce
 
17287c8
 
 
 
 
 
 
 
 
a55b0ce
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17287c8
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
---
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.”