spnda

spnda serve [--port port] [--upstream url] [--threshold n] [--block] [--k n]spnda eval [samples...] [--context text] [--threshold n]spnda bench [--iterations n]spnda version

spnda is the command-line entry point for Spanda, an epistemic-uncertainty engine for large language model outputs. It clusters sampled answers by normalized exact match, computes a combined risk score R_sc from Shannon entropy and modal dominance, and classifies the result (consensus, divergence, or suspected mode collapse).The same binary can sit in front of any OpenAI-compatible server as spnda serve. For each non-streaming chat or completions request it may raise n to K, call the upstream, score the candidate texts, collapse the response back to the dominant answer when the client asked for a single choice, and attach telemetry:

X-Spanda-Rsc, X-Spanda-Decision, X-Spanda-Safe, X-Spanda-Latency-Ms (Python) or X-Spanda-Latency-Us (native), plus Prometheus GET /metrics, Kubernetes GET /healthz and GET /readyz.

serve

Start an OpenAI-compatible reverse proxy. Completions are forwarded to --upstream, sampled K times when the client requested n=1, scored for lexical consensus, then returned with X-Spanda-* headers (and an audit object on the JSON body).

Local listen port. Default 8080. Binds 0.0.0.0.

Base URL of the upstream OpenAI-compatible API (OpenAI, Ollama, vLLM, Groq, and similar). Default is the OpenAI public API.

R_sc uncertainty cutoff in the range 0..1. Default 0.35. Higher values are more permissive.

When a reply is scored unsafe, return HTTP 422 instead of forwarding it. Without this flag the gateway still injects headers and audit fields.

Number of completion paths to sample when the client sent n=1. Default 3. Used only for non-streaming chat/completions.

Score one or more candidate strings and print a JSON receipt (risk score, dominant answer, decision, safety flag). Needs at least one sample.

Optional grounding text. When set, unanimous but ungrounded answers can be flagged as mode-collapse risk rather than consensus.

Time the native mathematical kernel. Present on the compiled Rust binary; the pure-Python CLI does not implement this subcommand.

Benchmark loop count. Default 100000 on the Rust binary.

Print package version and a short description of the engine.

Python installer only: skip exec of a sibling native spnda binary and keep the stdlib gateway.

SPANDA_UPSTREAM

Upstream LLM base URL. Default https://api.openai.com/v1 in the Python gateway.

Listen port for serve. Default 8080.

R_sc cutoff. Default 0.35.

Set to 1 to reject unsafe completions with HTTP 422.

Sample count when the client sends n=1. Default 3.

The score is lexical, not semantic. It is intended for structured answers (math, code, tool arguments, short factual extraction), not free-form prose where paraphrases are expected. On large ungrounded models, identical wrong answers can look like high-confidence consensus; pass --context or retrieval text if that failure mode matters.serve listens on all interfaces. The Python package is MIT; the compiled Rust gateway is Business Source License 1.1 and is not a drop-in substitute for a neural NLI judge. bench exists only on the native binary. Upstream API keys still have to be supplied by the client (the proxy forwards Authorization).

Spanda was written by Bhupen Nayak at BRHMN Labs. It implements exact-match normalized entropy as a CPU-only stand-in for neural Semantic Entropy clustering. Version 0.3.0 ships the spnda CLI (Python console script and Rust binary) together with a Python SDK. A companion write-up is archived at DOI 10.5281/zenodo.22233648.

ollama(1), vllm(1), openai(1), aichat(1), llm(1), curl(1)

Source code