> ## Documentation Index > Fetch the complete documentation index at: https://hillock.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Deterministic Gating: How Hillock Prevents Hallucinations > How Hillock's HDC cosine gate blocks ungrounded queries before any LLM call — the same query always produces the same pass/block decision, guaranteed. Standard LLMs have no mechanism to refuse a question they cannot answer from verified knowledge — they generate plausible-sounding text regardless of whether that text is grounded in fact. Hillock solves this with a deterministic gate that sits between user queries and the LLM renderer. Before any generative call is made, every query is encoded as a 10,000-dimensional hypervector and scored against the knowledge graph using cosine similarity. If the score falls below a configurable threshold, the query is blocked and a refusal is returned — no LLM call, no hallucination possible. The gate is mathematically deterministic: the same query always produces the same gate decision. *** ## The HYDRA MaxSim Gate Every user query passes through the HYDRA scoring pipeline before any retrieval or generation happens. ### Step-by-Step Gate Flow ### Encode the Query The query is tokenized and each token is encoded into a bipolar `±1` hypervector using the dual-path encoder (SubwordHDC + GloVe SimHash). Entity tokens that already exist in the HDC codebook use their pre-allocated hypervectors; unknown tokens are encoded fresh via morphological n-gram hashing. ### Build Candidate Fact Hypervectors For each candidate fact `(S, P, O)` retrieved from the knowledge graph for the detected entities, TALON assembles a set of hypervectors: one for the predicate `P`, and one each for subject `S` and object `O` (resolved through the codebook if available, or freshly encoded if not). ### Stage 1 — Early Rejection (2,000 dimensions) The first 2,000 dimensions of all query and fact hypervectors are packed into compact `uint64` words. Pairwise cosine similarity is computed via Hamming distance. If the MaxSim score across all fact hypervectors is below `τ_early = 0.20`, the fact is immediately rejected. This eliminates obviously irrelevant facts in microseconds without touching the full 10,000-dimensional representation. ### Stage 2 — Full Scoring (10,000 dimensions) Candidates that survive early rejection are re-scored against all 10,000 dimensions. The final HYDRA score is the mean of MaxSim over all query hypervector components. ### Gate Decision If the full-dimensional HYDRA score ≥ `0.55` **and** predicate alignment ≥ `0.35`: → **PASS** — matched facts forwarded to the LLM renderer. If either condition fails: → **BLOCK** — refusal response returned immediately. ### Configuring the Threshold The threshold is set as `HDC_THRESHOLD = 0.55` in `config.py`. Adjust it based on your precision/recall tradeoff: ```python theme={null} # config.py HDC_THRESHOLD = 0.55 # Default: balanced precision/recall # HDC_THRESHOLD = 0.45 # More permissive — allows paraphrase queries through # HDC_THRESHOLD = 0.65 # More conservative — only near-exact matches pass ``` Lower values let more queries through (higher recall, more risk of weak matches). Higher values enforce strict semantic proximity (higher precision, may reject valid paraphrases). *** ## Three Answering Modes When a query passes the gate, the matched facts are handed to the LLM for rendering. The rendering behavior is controlled by the `verbosity_mode` setting, which governs the system prompt and what additional context (priming, HDC traces) is included. Only the verified facts from the knowledge graph, translated into one sentence. No inference, no added context, no elaboration. The LLM acts as a fact formatter, not a reasoner. **System prompt excerpt:** > "You are a professional fact renderer. Translate ONLY the provided fact into one sentence. Do not add any extra context, historical assumptions, or details." **Best for:** Production agents where hallucination is unacceptable. Regulatory, medical, or legal contexts. Automated pipelines where responses are parsed programmatically. ```python theme={null} # Python hillock.verbosity_mode = "STRICT" ``` ``` # CLI /mode strict ``` Facts from the knowledge graph, plus one sentence of natural context. Sources are always cited. The LLM may reason carefully but must clearly distinguish known facts from any inference. **System prompt excerpt:** > "You may add one short sentence of natural conversational context, but do NOT invent specific facts. Always briefly mention the source document provided in the fact." **Best for:** General-purpose assistants where some natural language fluency is desirable but source attribution matters. Research assistants, document Q\&A. ```python theme={null} # Python hillock.verbosity_mode = "BALANCED" ``` ``` # CLI /mode balanced ``` Natural language responses that wrap the verified facts in engaging dialogue. The LLM may weave in Hebbian priming associations (surfacing related entities) and ask follow-up questions. Strict factual grounding is maintained — no names, dates, or facts outside the verified data may be invented. **System prompt excerpt:** > "You are encouraged to wrap the fact in natural, engaging dialogue. If memory associations are provided, seamlessly weave them into the conversation by asking if they want to hear about them. Do NOT invent any facts, dates, or names outside the verified data." **Best for:** Consumer-facing agents, interactive tutoring, personal knowledge assistants where a robotic tone would harm user experience. ```python theme={null} # Python hillock.verbosity_mode = "CONVERSATIONAL" ``` ``` # CLI /mode conversational ``` *** ## Mathematical Guarantee The gate is a cosine similarity comparison in a 10,000-dimensional Euclidean space. There are no random tie-breaking operations, no sampling, and no temperature parameters involved. The same query string, encoded with the same GloVe vocabulary and the same fixed random projection matrix `R` (seeded at `seed=42`), always produces the same hypervector and thus the same gate decision. ### The Cosine Similarity Formula ``` sim(q, d) = (q · d) / (|q| × |d|) ``` Where: * `q` — the query hypervector (mean of per-token hypervectors) * `d` — the fact hypervector (predicate + entity components) * `·` — dot product * `|·|` — L2 norm In bipolar `±1` space, this simplifies to: ``` sim(q, d) = (1/D) × Σᵢ qᵢ × dᵢ ``` Where `D = 10000`. The cosine similarity score is bounded in `[-1.0, 1.0]`. Random orthogonal hypervectors score near `0.0`; near-identical encodings score near `1.0`. The threshold of `0.55` sits well above the noise floor of random pairs at this dimensionality. ### Why High Dimensionality Matters At 10,000 dimensions, the expected cosine similarity between two randomly generated bipolar hypervectors is `0.0` with a standard deviation of `1/√D ≈ 0.01`. This means scores above `0.55` are more than 55 standard deviations from the noise floor — statistically impossible for unrelated concepts to produce false positives. This is the **concentration of measure** property that makes HDC gates reliable. *** ## What a Blocked Query Looks Like When a query fails the gate, Hillock returns a structured refusal. The exact format depends on `verbosity_mode`: ``` Hillock > I do not have verified information about that. ``` No LLM call is made. The response is a hardcoded string, returned in microseconds. The LLM is called with a refusal-specific prompt. It explains the knowledge gap and asks the user to provide a document to read: ``` Hillock (Renderer) > That's a great question, but I don't have any verified facts about that topic in my memory yet. If you have a document or article about it, I can read it and then answer accurately. What would you like to share? ``` The system prompt explicitly forbids the LLM from inventing an answer: > "Do NOT invent an answer." The return code for this path is `"CONVERSATIONAL_REFUSAL"` (vs `"DETERMINISTIC_GATED_FALLBACK"` for STRICT mode). ### Inspecting Gate Decisions Enable debug logging to see HYDRA scores for every evaluated fact: ```python theme={null} hillock.debug_level = "LOW" # Prints MaxSim and PredAlign per fact hillock.debug_level = "FULL" # Same as LOW, includes HDC context fingerprint ``` ``` [DEBUG HDC HYDRA]: Fact [Marie_Curie discovered Radioactivity] MaxSim: 0.6821 | PredAlign: 0.4903 → PASS [DEBUG HDC HYDRA]: Fact [Alan_Turing born_in London] MaxSim: 0.1143 | PredAlign: 0.0812 → BLOCKED (early rejection) ``` *** **Seed knowledge and benchmarks:** 4 of Hillock's 7 seed triples overlap common knowledge-graph evaluation target sets (e.g., `Marie_Curie discovered Radioactivity`, `Alan_Turing cracked Enigma`). If you're running your own accuracy benchmarks, either reset the database with `kg.clear_and_reinitialize()` before seeding with your own data, or account for the 4 overlapping triples in your evaluation methodology. Failure to do so will artificially inflate recall metrics on standard KG benchmarks. **Use STRICT mode for production agents.** CONVERSATIONAL mode is designed for exploratory, human-facing interactions. In any automated pipeline — tool-use agents, RAG pipelines, structured data extraction — set `hillock.verbosity_mode = "STRICT"` to eliminate any possibility of the LLM renderer adding unverified elaborations. STRICT mode also skips the LLM call entirely on refusals, making blocked queries essentially free in terms of latency and token cost. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.