Update README.md

README.md

@@ -1,10 +1,54 @@
 ---
-title: README
-emoji: 🦀
-colorFrom: blue
-colorTo: pink
+title: groundlens
+emoji: 📐
+colorFrom: yellow
+colorTo: red
 sdk: static
 pinned: false
 ---
 
-Edit this `README.md` markdown file to author your organization card.
+# Groundlens
+
+
+<p align="center">
+  <img src="logo.png" alt="groundlens" width="200">
+</p>
+
+Geometric methods for LLM grounding verification. No second LLM. Deterministic. Same inputs, same scores, every time.
+
+## What we do
+
+We detect LLM hallucinations using embedding geometry — not by asking another model to judge the output. Two metrics, each targeting a different failure mode:
+
+- **SGI** (Semantic Grounding Index) — measures whether a response actually used the source material it was given. Built for RAG pipeline verification.
+- **DGI** (Directional Grounding Index) — measures whether a response follows geometric patterns typical of grounded answers. Works without any source context.
+
+Both methods run a single embedding call. Deterministic. Auditable by design.
+
+## Research
+
+Three peer-reviewed papers form the foundation:
+
+1. **Semantic Grounding Index** ([arXiv:2512.13771](https://arxiv.org/abs/2512.13771)) — ratio-based grounding verification for RAG systems.
+2. **A Geometric Taxonomy of Hallucinations** ([arXiv:2602.13224](https://arxiv.org/abs/2602.13224v3)) — three-type hallucination classification with a confabulation benchmark.
+3. **Rotational Dynamics of Factual Constraint Processing** ([arXiv:2603.13259](https://arxiv.org/abs/2603.13259)) — transformers reject wrong answers via rotation, not rescaling. Phase transition at 1.6B parameters.
+
+## Use groundlens
+
+| How | What |
+|-----|------|
+| **Python library** | `pip install groundlens` — [GitHub](https://github.com/groundlens-dev/groundlens) · [Docs](https://docs.groundlens.dev) |
+| **MCP server** | `pip install groundlens-mcp` — works with Claude Desktop, Cursor, Windsurf — [GitHub](https://github.com/groundlens-dev/groundlens-mcp) |
+| **REST API** | [groundlens-api](https://huggingface.co/spaces/groundlens/groundlens-api) — hosted on this Space, Swagger docs at `/docs` |
+| **Interactive demo** | [groundlens-demo](https://huggingface.co/spaces/groundlens/groundlens-demo) — try it without installing anything |
+
+## Philosophy
+
+groundlens is verification triage, not truth detection. It tells you which responses earned the right to be trusted and which need human review. We publish our AUROC numbers even when they're unflattering. We document what we can't detect (Type III confabulations) as a theorem, not a footnote.
+
+## Links
+
+- [groundlens.dev](https://groundlens.dev)
+- [docs.groundlens.dev](https://docs.groundlens.dev)
+- [GitHub](https://github.com/groundlens-dev)
+- Contact: javier@jmarin.info