Spaces:
Sleeping
Sleeping
File size: 3,283 Bytes
6d74c84 | 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 | ---
title: groundlens API
emoji: 📐
colorFrom: yellow
colorTo: red
sdk: docker
pinned: false
license: mit
tags:
- hallucination-detection
- llm-evaluation
- rag
- grounding
- groundlens
- api
short_description: REST API for geometric LLM hallucination detection
---
# groundlens API
REST API for [groundlens](https://groundlens.dev) — LLM hallucination detection using embedding geometry.
No second LLM. Deterministic. Same inputs → same scores.
## Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/check` | Auto-selects SGI or DGI based on context |
| `POST` | `/v1/sgi` | Context-based grounding check |
| `POST` | `/v1/dgi` | Context-free grounding check |
| `GET` | `/health` | Liveness + model status |
| `GET` | `/docs` | Interactive Swagger UI |
## Quick start
### Check without context (DGI)
```bash
curl -X POST https://groundlens-groundlens-api.hf.space/v1/check \
-H "Content-Type: application/json" \
-d '{
"question": "What is the capital of France?",
"response": "The capital of France is Paris."
}'
```
### Check with context (SGI)
```bash
curl -X POST https://groundlens-groundlens-api.hf.space/v1/check \
-H "Content-Type: application/json" \
-d '{
"question": "What does our policy cover?",
"response": "The policy covers fire, flood, and theft damage to residential properties.",
"context": "HomeShield Insurance Policy: Coverage includes damage from fire, flood, and theft for residential properties within the continental United States."
}'
```
### Python
```python
import requests
r = requests.post(
"https://groundlens-groundlens-api.hf.space/v1/check",
json={
"question": "What is the capital of France?",
"response": "The capital of France is Paris.",
},
)
print(r.json()["verdict"]) # GROUNDED
```
### JavaScript
```javascript
const res = await fetch("https://groundlens-groundlens-api.hf.space/v1/check", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
question: "What is the capital of France?",
response: "The capital of France is Paris.",
}),
});
const data = await res.json();
console.log(data.verdict); // GROUNDED
```
## Response format
```json
{
"verdict": "GROUNDED",
"flagged": false,
"method": "DGI (Directional Grounding Index)",
"score": 0.4521,
"threshold": 0.30,
"explanation": "The response follows patterns typical of grounded answers.",
"detail": {
"interpretation": "Positive directional alignment with grounded response patterns."
},
"latency_ms": 45
}
```
## Self-hosting
```bash
git clone https://github.com/groundlens-dev/groundlens-api.git
cd groundlens-api
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8000
```
Or with Docker:
```bash
docker build -t groundlens-api .
docker run -p 8000:7860 groundlens-api
```
## Links
- [groundlens library](https://github.com/groundlens-dev/groundlens) — `pip install groundlens`
- [MCP Server](https://github.com/groundlens-dev/groundlens-mcp) — for Claude Desktop, Cursor, Windsurf
- [Demo](https://huggingface.co/spaces/groundlens/groundlens-demo) — interactive web UI
- [Documentation](https://docs.groundlens.dev)
- [Website](https://groundlens.dev)
|