# Spanda

> Zero-cost epistemic uncertainty quantification and hallucination detection for LLMs, operating ~90,000x faster than neural Semantic Entropy without requiring a GPU.

Spanda (package name `spnda` on PyPI) is a research-backed Python library and Rust-powered gateway for detecting hallucinations in Large Language Models without the computational overhead of traditional neural Semantic Entropy. Published as a preprint on Zenodo (DOI: 10.5281/zenodo.22233648) by Bhupen Nayak of Spanda Research, the project is actively developed on GitHub under a dual MIT/BSL 1.1 license and reached v0.2.2 in September 2026.

## What It Is

Spanda introduces the **Exact-Match Normalized Entropy** metric ($R_{sc}$), a zero-parameter, zero-GPU uncertainty score computed directly over deterministic lexical clusters of sampled LLM outputs. Instead of running 45+ neural NLI forward passes per query (as Semantic Entropy requires), Spanda computes the same discriminative signal in under one microsecond using pure CPU arithmetic. The library ships as a Python SDK with zero third-party dependencies, plus an optional compiled Rust core engine and OpenAI-compatible reverse-proxy gateway (`spnda serve`).

## Core Algorithm and Empirical Findings

The $R_{sc}$ score combines normalized Shannon entropy over answer clusters with modal dominance weighting (α = 0.5). Empirical evaluation across models from 1.5B to 120B parameters revealed two key findings:

- **Coherence Scaling Law:** For mid-sized models (7B–27B), $R_{sc}$ achieves AUROC of 0.889 on GSM8K mathematical reasoning, matching DeBERTa-v3 NLI cross-encoders at zero GPU cost.
- **Confident Mode Collapse:** At frontier scale (120B+), RLHF alignment causes models to hallucinate the *same* incorrect answer across all sampled paths, inverting AUROC to 0.091 and defeating self-consistency assumptions. The project flags this as a critical safety concern requiring external RAG grounding.

## Architecture and Deployment Model

Spanda is structured as a dual-component system:

- **Python SDK (`spanda`):** A pure-stdlib client library with a 1-line `spanda.wrap()` drop-in for any OpenAI-compatible client. Integrations are provided for LangChain, LlamaIndex, and LiteLLM.
- **Rust Core Engine & Gateway (`spnda`):** A compiled binary serving an OpenAI-compatible HTTP proxy with sub-millisecond overhead (76.3 µs net latency), Prometheus `/metrics`, Kubernetes health probes, and structured JSON logging. The gateway adds epistemic headers (`X-Spanda-Rsc`, `X-Spanda-State`, `X-Spanda-Decision`) to every proxied response.

The gateway benchmarks at 652 nanoseconds per evaluation and 1.53 million evaluations per second on a single CPU core, with a 2.98 MB idle memory footprint versus ~1.8 GB GPU VRAM for the DeBERTa baseline.

## Operational Envelope and Tradeoffs

The project's README explicitly scopes where Spanda is and is not appropriate:

- **Recommended:** Math, code, structured QA, and canonical factual RAG extraction on 7B–70B models; high-throughput production APIs where 90 ms GPU latency is unacceptable.
- **Use Neural SE instead:** Free-form paraphrase QA on models below 7B, where surface phrasing varies even for semantically equivalent answers.
- **Do not use alone:** Ungrounded factual recall on frontier models (>100B), where Confident Mode Collapse makes self-consistency an unreliable signal.

A 2-Tier Cascaded Guardrail API (`CascadedGuardrail`) combines sub-millisecond consensus filtering with context grounding checks and agent tool-call argument verification, targeting mission-critical RAG and autonomous agent pipelines.

## Update: v0.2.2 — Smart Numeric, Polar & CoT Canonicalizer

The latest release (v0.2.2, published September 7, 2026) is named "Smart Numeric, Polar & CoT Canonicalizer," indicating active work on improving the deterministic normalization layer that partitions sampled answers into equivalence classes. The repository was last pushed on September 12, 2026, and the project status is listed as Active on Zenodo. The Rust core engine is licensed under BSL 1.1 and is scheduled to automatically convert to Apache 2.0 on January 1, 2030.

## Features
- Zero-cost epistemic uncertainty quantification (no GPU required)
- Exact-Match Normalized Entropy (R_sc) metric
- 1-line drop-in wrapper for OpenAI-compatible clients (spanda.wrap)
- Compiled Rust gateway with OpenAI-compatible reverse proxy
- Sub-microsecond evaluation latency (<1 µs)
- 7-state epistemic classification
- Confident Mode Collapse detection
- 2-Tier Cascaded Guardrail for RAG and agent pipelines
- Agent tool-call argument verification
- Batch processing API (batch_compute_rsc)
- LangChain, LlamaIndex, and LiteLLM integrations
- Prometheus /metrics endpoint for Grafana observability
- Kubernetes liveness and readiness probes
- Structured JSON logging for Datadog/CloudWatch/Splunk
- Docker and Kubernetes deployment support
- Zero third-party Python dependencies

## Integrations
OpenAI, Groq, Ollama, LangChain, LlamaIndex, LiteLLM, Prometheus, Grafana, Datadog, CloudWatch, Splunk, Docker, Kubernetes

## Platforms
WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.2.2

## Links
- Website: https://doi.org/10.5281/zenodo.22233648
- Documentation: https://github.com/Adarshent/Spnda
- Repository: https://github.com/Adarshent/Spnda
- EveryDev.ai: https://www.everydev.ai/tools/spanda