# 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
