spnda 0.2.0__tar.gz

spnda-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bhupen Nayak, BRHMN Labs Private Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spnda-0.2.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: spnda
+Version: 0.2.0
+Summary: Zero-cost epistemic uncertainty quantification & enterprise cascaded guardrails for LLMs
+Author: BRHMN Labs Private Limited
+Author-email: Bhupen Nayak <bhupennayak@icloud.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Adarshent/Spnda
+Project-URL: Repository, https://github.com/Adarshent/Spnda.git
+Project-URL: Bug Tracker, https://github.com/Adarshent/Spnda/issues
+Project-URL: Paper (Zenodo), https://doi.org/10.5281/zenodo.22233648
+Project-URL: ORCID, https://orcid.org/0009-0005-6038-1356
+Keywords: llm,hallucination-detection,guardrails,semantic-entropy,epistemic-uncertainty,ai-safety,self-consistency,rag,agents,tool-calling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+# ⚡ Spanda ($R_{sc}$)
+### Zero-Cost Epistemic Uncertainty Quantification for Large Language Models
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22233648.svg)](https://doi.org/10.5281/zenodo.22233648)
+[![ORCID](https://img.shields.io/badge/ORCID-0009--0005--6038--1356-green.svg)](https://orcid.org/0009-0005-6038-1356)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#)
+[![Tests Passing](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#)
+
+*Detect LLM hallucinations and quantify uncertainty in microseconds without secondary NLI cross-encoders.*
+
+---
+
+</div>
+
+## 📌 Overview
+
+Traditional epistemic uncertainty estimation in LLMs relies on **Semantic Entropy (SE)** ([Kuhn et al., 2023](https://arxiv.org/abs/2302.09664); [Farquhar et al., Nature 2024](https://www.nature.com/articles/s41586-024-07421-0)). While effective, Semantic Entropy requires clustering $K$ sampled generation paths using pairwise bidirectional NLI entailment classifiers (e.g., DeBERTa-v3-base). 
+
+This introduces two severe production bottlenecks:
+1. **Quadratic Cost:** $\binom{K}{2}$ forward passes per query (45 neural evaluations for $K=10$).
+2. **Serving Latency:** Adds $\sim$90 ms of GPU overhead per inference call, making it unusable for high-throughput production serving.
+
+**Spanda** introduces **Exact-Match Normalized Entropy ($R_{sc}$)**: a zero-parameter, zero-GPU metric that computes uncertainty directly over deterministic lexical clusters. 
+
+Across empirical evaluations spanning two orders of magnitude (**1.5B to 120B parameters**), Spanda matches or exceeds neural Semantic Entropy on structured reasoning while operating **~90,000$\times$ faster** ($< 1\,\mu\text{s}$ vs. $92.4\,\text{ms}$).
+
+---
+
+## 🔬 Key Empirical Discoveries
+
+### 1. The Coherence Scaling Law
+As model capacity increases from 1.5B to 27B parameters, internal reasoning coherence causes correct predictions to naturally converge to identical lexical sequences. On mathematical reasoning (**GSM8K**), exact-match AUROC scales monotonically:
+
+$$\text{AUROC}_{\text{GSM8K}}: \underbrace{0.577}_{\text{1.5B}} \longrightarrow \underbrace{0.706}_{\text{7B}} \longrightarrow \mathbf{\underbrace{0.889}_{\text{27B}}} \quad (p = 1.89 \times 10^{-28})$$
+
+At **7B+ parameters**, Spanda achieves the exact same discriminative power as heavy DeBERTa-v3 NLI cross-encoders, rendering the neural clustering step redundant for reasoning.
+
+### 2. Confident Mode Collapse (Safety Warning)
+At the **120B frontier scale** on ungrounded factual recall (TriviaQA), the model exhibits **Confident Mode Collapse**: its parametric memory and RLHF tuning cause it to hallucinate the *exact same incorrect answer* identically across all $K$ paths. This yields an **inverted AUROC of 0.091** ($d = -2.23, p = 8.28 \times 10^{-15}$).
+
+> ⚠️ **Critical Safety Implication:** Any system using self-consistency or agreement as a proxy for truth will be systematically deceived by frontier models on ungrounded factual recall. External grounding (RAG) is mandatory in this regime.
+
+---
+
+## 📊 Benchmark Results
+
+| Model Scale | Benchmark | Accuracy | Spanda ($R_{sc}$) AUROC | Neural SE AUROC | Latency | GPU Req. |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
+| **Qwen-1.5B** | GSM8K | 11.4% | 0.577 | **0.584** | $<1\,\mu\text{s}$ | None |
+| **Qwen-1.5B** | TriviaQA | 32.0% | 0.797 | **0.801** | $<1\,\mu\text{s}$ | None |
+| **Mistral-7B** | GSM8K | 8.2% | **0.706** | 0.705 | $<1\,\mu\text{s}$ | None |
+| **Mistral-7B** | TriviaQA | 45.0% | 0.698 | **0.755** | $<1\,\mu\text{s}$ | None |
+| **Qwen-27B** | GSM8K | 61.2% | **0.889** | --- | $<1\,\mu\text{s}$ | None |
+| **DeBERTa Baseline** | *N/A* | --- | --- | --- | **$\sim$92.4 ms** | Required |
+
+---
+
+## 📐 Mathematical Formulation
+
+Given $K$ sampled final answers $\{y_1, \dots, y_K\}$ for prompt $x$, deterministic normalization partitions them into $n$ equivalence classes $\{C_1, \dots, C_n\}$ with empirical probabilities $w_i = \frac{|C_i|}{K}$.
+
+The **Normalized Shannon Entropy** is:
+$$H_{\text{norm}} = \begin{cases} 0 & \text{if } n = 1 \\ \displaystyle\frac{-\sum_{i=1}^n w_i \ln w_i}{\ln K} & \text{if } n > 1 \end{cases}$$
+
+The combined **Spanda Risk Score ($R_{sc}$)** balances entropy dispersion with modal dominance ($w_{\max} = \max_i w_i$):
+$$R_{sc} = \alpha \cdot H_{\text{norm}} + (1 - \alpha) \cdot (1 - w_{\max}), \quad \alpha = 0.5$$
+
+- $R_{sc} = 0$: Complete consensus (model is confident).
+- $R_{sc} \to 1$: Maximum epistemic divergence (model is guessing / hallucinating).
+
+---
+
+## ⚡ Installation
+
+Spanda is lightweight and requires **zero third-party dependencies** (pure Python standard library).
+
+```bash
+pip install spanda
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/Adarshent/Spnda.git
+cd Spnda
+pip install -e .
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Basic Uncertainty Quantification
+```python
+from spanda import compute_rsc
+
+# High-consensus query (Model is confident)
+samples_confident = ["Paris", "paris.", "Paris", "Paris", "Paris"]
+res_conf = compute_rsc(samples_confident)
+
+print(f"R_sc Score: {res_conf['rsc']}")  # 0.0
+print(f"Dominant Answer: {res_conf['dominant_answer']}")  # 'Paris'
+
+# Uncertain / guessing query (Model is hallucinating)
+samples_uncertain = ["Berlin", "Rome", "Madrid", "London", "Paris"]
+res_unc = compute_rsc(samples_uncertain)
+
+print(f"R_sc Score: {res_unc['rsc']}")  # 0.9 (High risk!)
+```
+
+### 2. Hallucination Detection Guardrail
+```python
+from spanda import detect_hallucination
+
+samples = ["42", "42", "24", "17", "99"]
+guard = detect_hallucination(samples, threshold=0.35)
+
+if guard["is_uncertain"]:
+    print(f"🚨 Hallucination Warning (R_sc = {guard['rsc']}). Routing to RAG / Human Review.")
+else:
+    print(f"✅ Safe output: {guard['dominant_answer']}")
+```
+
+### 3. High-Throughput Batch Processing
+```python
+from spanda import batch_compute_rsc
+
+batch = [
+    ["Answer A", "Answer A", "Answer A"],
+    ["Choice 1", "Choice 2", "Choice 3"]
+]
+
+results = batch_compute_rsc(batch)
+for r in results:
+    print(r["rsc"], r["dominant_answer"])
+```
+
+### 4. Enterprise Cascaded Guardrail (RAG & Autonomous Agents)
+
+For mission-critical production pipelines, Spanda provides a **2-Tier Cascaded Guardrail** that combines sub-millisecond consensus filtering with context grounding and tool-call safety:
+
+```python
+from spanda import CascadedGuardrail
+
+guard = CascadedGuardrail(
+    uncertainty_threshold=0.3,
+    grounding_threshold=0.15
+)
+
+# 1. RAG Query with Mode Collapse Protection
+rag_context = "Documentation: The production cluster runs in us-east-1."
+unanimous_hallucination = ["eu-west-3 Paris", "eu-west-3 Paris", "eu-west-3 Paris"]
+
+receipt = guard.evaluate(unanimous_hallucination, context=rag_context)
+print(receipt.decision)       # 'MODE_COLLAPSE_RISK'
+print(receipt.is_safe)        # False (Unanimous agreement, but 0% grounded in source!)
+print(receipt.tier_executed)  # Tier 2
+print(receipt.latency_ms)     # < 0.05 ms
+
+# 2. Agent Tool Call Argument Verification (e.g. preventing bad 'rm')
+tool_calls = [
+    {"command": "rm -rf /var/cache"},
+    {"command": "rm -rf /var/log"},  # Conflict detected across parallel paths!
+]
+agent_receipt = guard.evaluate_tool_calls(tool_calls)
+print(agent_receipt.decision) # 'TOOL_ARG_MISMATCH' (Execution blocked!)
+
+# 3. Export SOC2 Audit Receipt
+import json
+print(json.dumps(receipt.to_dict(), indent=2))
+```
+
+---
+
+## 🛡️ Operational Envelope
+
+| Use Case / Architecture | Recommendation | Rationale |
+| :--- | :---: | :--- |
+| **Math, Code & Structured QA (7B–70B)** | ✅ **Recommended** | Coherence Scaling Law ensures exact-match matches neural SE at 0 cost. |
+| **High-Throughput Production APIs** | ✅ **Recommended** | 90,000x latency reduction without GPU requirements. |
+| **Free-form Paraphrase QA (<7B)** | ⚠️ **Use Neural SE** | Small models produce inconsistent surface phrasing. |
+| **Ungrounded Facts on Frontier Models (>100B)** | ❌ **Do Not Use Alone** | Subject to **Confident Mode Collapse**; must combine with retrieval (RAG). |
+
+---
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+python3 -m unittest discover tests
+```
+
+---
+
+## 📄 Citation
+
+If you use Spanda in your research or production systems, please cite:
+
+```bibtex
+@article{nayak2026spanda,
+  title={Spanda: Zero-Cost Lexical Entropy Matches Neural Semantic Uncertainty---Until Frontier Models Break It},
+  author={Nayak, Bhupen},
+  journal={arXiv preprint},
+  year={2026},
+  doi={10.5281/zenodo.22233648},
+  url={https://doi.org/10.5281/zenodo.22233648}
+}
+```
+
+---
+
+## 📜 License
+
+This project is licensed under the [MIT License](LICENSE) - see the LICENSE file for details.

spnda-0.2.0/README.md

@@ -0,0 +1,219 @@
+<div align="center">
+
+# ⚡ Spanda ($R_{sc}$)
+### Zero-Cost Epistemic Uncertainty Quantification for Large Language Models
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22233648.svg)](https://doi.org/10.5281/zenodo.22233648)
+[![ORCID](https://img.shields.io/badge/ORCID-0009--0005--6038--1356-green.svg)](https://orcid.org/0009-0005-6038-1356)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#)
+[![Tests Passing](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#)
+
+*Detect LLM hallucinations and quantify uncertainty in microseconds without secondary NLI cross-encoders.*
+
+---
+
+</div>
+
+## 📌 Overview
+
+Traditional epistemic uncertainty estimation in LLMs relies on **Semantic Entropy (SE)** ([Kuhn et al., 2023](https://arxiv.org/abs/2302.09664); [Farquhar et al., Nature 2024](https://www.nature.com/articles/s41586-024-07421-0)). While effective, Semantic Entropy requires clustering $K$ sampled generation paths using pairwise bidirectional NLI entailment classifiers (e.g., DeBERTa-v3-base). 
+
+This introduces two severe production bottlenecks:
+1. **Quadratic Cost:** $\binom{K}{2}$ forward passes per query (45 neural evaluations for $K=10$).
+2. **Serving Latency:** Adds $\sim$90 ms of GPU overhead per inference call, making it unusable for high-throughput production serving.
+
+**Spanda** introduces **Exact-Match Normalized Entropy ($R_{sc}$)**: a zero-parameter, zero-GPU metric that computes uncertainty directly over deterministic lexical clusters. 
+
+Across empirical evaluations spanning two orders of magnitude (**1.5B to 120B parameters**), Spanda matches or exceeds neural Semantic Entropy on structured reasoning while operating **~90,000$\times$ faster** ($< 1\,\mu\text{s}$ vs. $92.4\,\text{ms}$).
+
+---
+
+## 🔬 Key Empirical Discoveries
+
+### 1. The Coherence Scaling Law
+As model capacity increases from 1.5B to 27B parameters, internal reasoning coherence causes correct predictions to naturally converge to identical lexical sequences. On mathematical reasoning (**GSM8K**), exact-match AUROC scales monotonically:
+
+$$\text{AUROC}_{\text{GSM8K}}: \underbrace{0.577}_{\text{1.5B}} \longrightarrow \underbrace{0.706}_{\text{7B}} \longrightarrow \mathbf{\underbrace{0.889}_{\text{27B}}} \quad (p = 1.89 \times 10^{-28})$$
+
+At **7B+ parameters**, Spanda achieves the exact same discriminative power as heavy DeBERTa-v3 NLI cross-encoders, rendering the neural clustering step redundant for reasoning.
+
+### 2. Confident Mode Collapse (Safety Warning)
+At the **120B frontier scale** on ungrounded factual recall (TriviaQA), the model exhibits **Confident Mode Collapse**: its parametric memory and RLHF tuning cause it to hallucinate the *exact same incorrect answer* identically across all $K$ paths. This yields an **inverted AUROC of 0.091** ($d = -2.23, p = 8.28 \times 10^{-15}$).
+
+> ⚠️ **Critical Safety Implication:** Any system using self-consistency or agreement as a proxy for truth will be systematically deceived by frontier models on ungrounded factual recall. External grounding (RAG) is mandatory in this regime.
+
+---
+
+## 📊 Benchmark Results
+
+| Model Scale | Benchmark | Accuracy | Spanda ($R_{sc}$) AUROC | Neural SE AUROC | Latency | GPU Req. |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
+| **Qwen-1.5B** | GSM8K | 11.4% | 0.577 | **0.584** | $<1\,\mu\text{s}$ | None |
+| **Qwen-1.5B** | TriviaQA | 32.0% | 0.797 | **0.801** | $<1\,\mu\text{s}$ | None |
+| **Mistral-7B** | GSM8K | 8.2% | **0.706** | 0.705 | $<1\,\mu\text{s}$ | None |
+| **Mistral-7B** | TriviaQA | 45.0% | 0.698 | **0.755** | $<1\,\mu\text{s}$ | None |
+| **Qwen-27B** | GSM8K | 61.2% | **0.889** | --- | $<1\,\mu\text{s}$ | None |
+| **DeBERTa Baseline** | *N/A* | --- | --- | --- | **$\sim$92.4 ms** | Required |
+
+---
+
+## 📐 Mathematical Formulation
+
+Given $K$ sampled final answers $\{y_1, \dots, y_K\}$ for prompt $x$, deterministic normalization partitions them into $n$ equivalence classes $\{C_1, \dots, C_n\}$ with empirical probabilities $w_i = \frac{|C_i|}{K}$.
+
+The **Normalized Shannon Entropy** is:
+$$H_{\text{norm}} = \begin{cases} 0 & \text{if } n = 1 \\ \displaystyle\frac{-\sum_{i=1}^n w_i \ln w_i}{\ln K} & \text{if } n > 1 \end{cases}$$
+
+The combined **Spanda Risk Score ($R_{sc}$)** balances entropy dispersion with modal dominance ($w_{\max} = \max_i w_i$):
+$$R_{sc} = \alpha \cdot H_{\text{norm}} + (1 - \alpha) \cdot (1 - w_{\max}), \quad \alpha = 0.5$$
+
+- $R_{sc} = 0$: Complete consensus (model is confident).
+- $R_{sc} \to 1$: Maximum epistemic divergence (model is guessing / hallucinating).
+
+---
+
+## ⚡ Installation
+
+Spanda is lightweight and requires **zero third-party dependencies** (pure Python standard library).
+
+```bash
+pip install spanda
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/Adarshent/Spnda.git
+cd Spnda
+pip install -e .
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Basic Uncertainty Quantification
+```python
+from spanda import compute_rsc
+
+# High-consensus query (Model is confident)
+samples_confident = ["Paris", "paris.", "Paris", "Paris", "Paris"]
+res_conf = compute_rsc(samples_confident)
+
+print(f"R_sc Score: {res_conf['rsc']}")  # 0.0
+print(f"Dominant Answer: {res_conf['dominant_answer']}")  # 'Paris'
+
+# Uncertain / guessing query (Model is hallucinating)
+samples_uncertain = ["Berlin", "Rome", "Madrid", "London", "Paris"]
+res_unc = compute_rsc(samples_uncertain)
+
+print(f"R_sc Score: {res_unc['rsc']}")  # 0.9 (High risk!)
+```
+
+### 2. Hallucination Detection Guardrail
+```python
+from spanda import detect_hallucination
+
+samples = ["42", "42", "24", "17", "99"]
+guard = detect_hallucination(samples, threshold=0.35)
+
+if guard["is_uncertain"]:
+    print(f"🚨 Hallucination Warning (R_sc = {guard['rsc']}). Routing to RAG / Human Review.")
+else:
+    print(f"✅ Safe output: {guard['dominant_answer']}")
+```
+
+### 3. High-Throughput Batch Processing
+```python
+from spanda import batch_compute_rsc
+
+batch = [
+    ["Answer A", "Answer A", "Answer A"],
+    ["Choice 1", "Choice 2", "Choice 3"]
+]
+
+results = batch_compute_rsc(batch)
+for r in results:
+    print(r["rsc"], r["dominant_answer"])
+```
+
+### 4. Enterprise Cascaded Guardrail (RAG & Autonomous Agents)
+
+For mission-critical production pipelines, Spanda provides a **2-Tier Cascaded Guardrail** that combines sub-millisecond consensus filtering with context grounding and tool-call safety:
+
+```python
+from spanda import CascadedGuardrail
+
+guard = CascadedGuardrail(
+    uncertainty_threshold=0.3,
+    grounding_threshold=0.15
+)
+
+# 1. RAG Query with Mode Collapse Protection
+rag_context = "Documentation: The production cluster runs in us-east-1."
+unanimous_hallucination = ["eu-west-3 Paris", "eu-west-3 Paris", "eu-west-3 Paris"]
+
+receipt = guard.evaluate(unanimous_hallucination, context=rag_context)
+print(receipt.decision)       # 'MODE_COLLAPSE_RISK'
+print(receipt.is_safe)        # False (Unanimous agreement, but 0% grounded in source!)
+print(receipt.tier_executed)  # Tier 2
+print(receipt.latency_ms)     # < 0.05 ms
+
+# 2. Agent Tool Call Argument Verification (e.g. preventing bad 'rm')
+tool_calls = [
+    {"command": "rm -rf /var/cache"},
+    {"command": "rm -rf /var/log"},  # Conflict detected across parallel paths!
+]
+agent_receipt = guard.evaluate_tool_calls(tool_calls)
+print(agent_receipt.decision) # 'TOOL_ARG_MISMATCH' (Execution blocked!)
+
+# 3. Export SOC2 Audit Receipt
+import json
+print(json.dumps(receipt.to_dict(), indent=2))
+```
+
+---
+
+## 🛡️ Operational Envelope
+
+| Use Case / Architecture | Recommendation | Rationale |
+| :--- | :---: | :--- |
+| **Math, Code & Structured QA (7B–70B)** | ✅ **Recommended** | Coherence Scaling Law ensures exact-match matches neural SE at 0 cost. |
+| **High-Throughput Production APIs** | ✅ **Recommended** | 90,000x latency reduction without GPU requirements. |
+| **Free-form Paraphrase QA (<7B)** | ⚠️ **Use Neural SE** | Small models produce inconsistent surface phrasing. |
+| **Ungrounded Facts on Frontier Models (>100B)** | ❌ **Do Not Use Alone** | Subject to **Confident Mode Collapse**; must combine with retrieval (RAG). |
+
+---
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+python3 -m unittest discover tests
+```
+
+---
+
+## 📄 Citation
+
+If you use Spanda in your research or production systems, please cite:
+
+```bibtex
+@article{nayak2026spanda,
+  title={Spanda: Zero-Cost Lexical Entropy Matches Neural Semantic Uncertainty---Until Frontier Models Break It},
+  author={Nayak, Bhupen},
+  journal={arXiv preprint},
+  year={2026},
+  doi={10.5281/zenodo.22233648},
+  url={https://doi.org/10.5281/zenodo.22233648}
+}
+```
+
+---
+
+## 📜 License
+
+This project is licensed under the [MIT License](LICENSE) - see the LICENSE file for details.

spnda-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spnda"
+version = "0.2.0"
+authors = [
+  { name = "Bhupen Nayak", email = "bhupennayak@icloud.com" },
+  { name = "BRHMN Labs Private Limited" },
+]
+description = "Zero-cost epistemic uncertainty quantification & enterprise cascaded guardrails for LLMs"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+keywords = [
+  "llm",
+  "hallucination-detection",
+  "guardrails",
+  "semantic-entropy",
+  "epistemic-uncertainty",
+  "ai-safety",
+  "self-consistency",
+  "rag",
+  "agents",
+  "tool-calling"
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/Adarshent/Spnda"
+"Repository" = "https://github.com/Adarshent/Spnda.git"
+"Bug Tracker" = "https://github.com/Adarshent/Spnda/issues"
+"Paper (Zenodo)" = "https://doi.org/10.5281/zenodo.22233648"
+"ORCID" = "https://orcid.org/0009-0005-6038-1356"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["spanda*"]

spnda-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spnda-0.2.0/spanda/__init__.py

@@ -0,0 +1,44 @@
+"""
+Spanda — Zero-Cost Epistemic Uncertainty & Cascaded Guardrails for LLMs.
+
+Detect hallucinations in LLM outputs using exact-match normalized entropy.
+90,000x faster than neural Semantic Entropy, zero GPU required.
+
+Paper: "Spanda: Zero-Cost Lexical Entropy Matches Neural Semantic Uncertainty
+        — Until Frontier Models Break It" (Nayak, 2026)
+
+Usage:
+    >>> from spanda import compute_rsc, detect_hallucination, CascadedGuardrail
+    >>> answers = ["42", "42", "42", "41", "43"]
+    >>> result = compute_rsc(answers)
+    >>> print(result)
+
+    >>> # Enterprise Cascaded Guardrail
+    >>> guard = CascadedGuardrail(uncertainty_threshold=0.3)
+    >>> receipt = guard.evaluate(answers, context="The answer is forty-two.")
+    >>> print(receipt)
+"""
+
+__version__ = "0.2.0"
+__author__ = "Bhupen Nayak"
+__email__ = "bhupennayak@icloud.com"
+
+from spanda.core import (
+    compute_rsc,
+    normalize_answer,
+    detect_hallucination,
+    batch_compute_rsc,
+)
+from spanda.guardrails import (
+    CascadedGuardrail,
+    AuditReceipt,
+)
+
+__all__ = [
+    "compute_rsc",
+    "normalize_answer",
+    "detect_hallucination",
+    "batch_compute_rsc",
+    "CascadedGuardrail",
+    "AuditReceipt",
+]

spnda-0.2.0/spanda/core.py

@@ -0,0 +1,96 @@
+import re
+import math
+import collections
+from typing import List, Dict, Any, Union
+
+def normalize_answer(text: str) -> str:
+    """
+    Deterministically normalizes a string for exact-match equivalence.
+    Lowercases, strips punctuation, and normalizes whitespace.
+    """
+    if not isinstance(text, str):
+        text = str(text)
+    
+    # Lowercase
+    text = text.lower()
+    
+    # Remove punctuation
+    text = re.sub(r'[^\w\s]', '', text)
+    
+    # Normalize whitespace
+    text = ' '.join(text.split())
+    
+    return text.strip()
+
+def compute_rsc(answers: List[str], alpha: float = 0.5) -> Dict[str, Any]:
+    """
+    Computes the Spanda (R_sc) exact-match entropy risk score for a set of sampled answers.
+    
+    Args:
+        answers: A list of K string answers sampled from an LLM.
+        alpha: The weighting factor for H_norm vs (1 - w_max). Default 0.5.
+        
+    Returns:
+        A dictionary containing the rsc score, components, and the dominant answer.
+    """
+    if not answers:
+        raise ValueError("The answers list cannot be empty.")
+        
+    K = len(answers)
+    
+    # 1. Normalize and cluster
+    normalized_answers = [normalize_answer(a) for a in answers]
+    counts = collections.Counter(normalized_answers)
+    
+    # 2. Compute probabilities (w_i)
+    w = [count / K for count in counts.values()]
+    n_clusters = len(counts)
+    
+    # 3. Compute normalized entropy H_norm
+    if n_clusters == 1:
+        h_norm = 0.0
+    else:
+        # Avoid math domain error by capping denominator
+        denom = math.log(K) if K > 1 else 1.0
+        h_norm = sum(-p * math.log(p) for p in w) / denom
+        
+    # 4. Compute modal dominance (w_max)
+    w_max = max(w)
+    
+    # 5. Compute R_sc
+    rsc = alpha * h_norm + (1 - alpha) * (1 - w_max)
+    
+    # Find the string representation of the dominant cluster
+    dominant_cluster_norm = counts.most_common(1)[0][0]
+    
+    # Find original string that mapped to dominant cluster (first occurrence)
+    dominant_answer = next(
+        ans for ans, norm in zip(answers, normalized_answers) 
+        if norm == dominant_cluster_norm
+    )
+    
+    return {
+        "rsc": round(rsc, 4),
+        "h_norm": round(h_norm, 4),
+        "w_max": round(w_max, 4),
+        "n_clusters": n_clusters,
+        "dominant_answer": dominant_answer,
+    }
+
+def detect_hallucination(answers: List[str], threshold: float = 0.3) -> Dict[str, Any]:
+    """
+    Convenience function that computes R_sc and returns a boolean flagging 
+    whether the model is likely hallucinating (R_sc > threshold).
+    
+    NOTE: On models > 100B params doing factual recall, confident mode collapse
+    may cause R_sc to be near 0 even for hallucinations. Use with caution on frontier models.
+    """
+    result = compute_rsc(answers)
+    result["is_uncertain"] = result["rsc"] > threshold
+    return result
+
+def batch_compute_rsc(batch_answers: List[List[str]]) -> List[Dict[str, Any]]:
+    """
+    Computes R_sc for a batch of sampled generations.
+    """
+    return [compute_rsc(answers) for answers in batch_answers]