Metadata-Version: 2.4
Name: geood
Version: 0.1.0
Summary: Geometric OOD detection for LLM hidden states
Author-email: Jesús Tabares Montilla <jesus@tabares.eu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/seetrex-ai/geood
Project-URL: Paper, https://zenodo.org/records/19039654
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0
Requires-Dist: transformers>=4.30
Requires-Dist: numpy>=1.24
Requires-Dist: accelerate>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# geood

Geometric OOD detection for LLM hidden states.

Perplexity misses out-of-distribution inputs when the model is fluent in the OOD domain. `geood` detects them using hidden-state geometry (intrinsic dimensionality + Mahalanobis distance).

**Paper:** [The Geometric Blind Spot of Perplexity](https://zenodo.org/records/19039654) (Tabares Montilla, 2026)

## Install

```bash
pip install geood
```

## Usage

```python
import geood

# Calibrate with your in-distribution texts (once)
detector = geood.calibrate("meta-llama/Llama-3-8B", ref_texts)

# Detect OOD (many times)
result = detector.detect("def quicksort(arr): ...")
print(result.is_ood)    # True
print(result.explain())  # "OOD detected: ref_dim=33.8, mahalanobis=12.3"

# Save/load for deployment
detector.save("my_detector.geood")
detector = geood.load("my_detector.geood")
```

## How it works

LLM hidden states for in-distribution inputs occupy a high-dimensional subspace. OOD inputs collapse to low dimensionality, even when perplexity says they're familiar. `geood` calibrates on your reference corpus and detects this geometric collapse.

## Key results

| Method | Code AUROC (LLaMA) | Code AUROC (Mistral) |
|---|---|---|
| Perplexity | 0.352 | 0.150 |
| **geood (Mahalanobis)** | **1.000** | **1.000** |
| **geood (Intrinsic dim)** | **1.000** | **1.000** |

Code has *lower* perplexity than math (2.57 vs 2.76) but collapses geometrically (dim 4 vs 34). Perplexity is blind; geometry detects it.

## License

MIT
