LlamaIndex Guardrails and Patterns

Use this page when your RAG or agent pipeline runs in LlamaIndex. It maps common orchestration and indexing failures to exact structural fixes in the Problem Map and gives a minimal recipe you can embed in an index or query engine.

Core acceptance

ΔS(question, retrieved) ≤ 0.45
coverage ≥ 0.70 for the target section
λ remains convergent across 3 paraphrases

Typical breakpoints and the right fix

Index built but retriever fires before it is ready Fix No.14: Bootstrap Ordering → Open
First queries after deploy fail due to env mismatch / missing secret Fix No.16: Pre-Deploy Collapse → Open
Background ingestion + retriever race → deadlocks or empty results Fix No.15: Deployment Deadlock → Open
Embedding similarity looks good, but meaning diverges Fix No.5: Embedding ≠ Semantic → Open
Answers cite wrong snippet or skip citations entirely Fix No.8: Retrieval Traceability → Open Enforce payload contracts: Data Contracts → Open
Hybrid retrievers (BM25 + dense) underperform single retriever Pattern: Query Parsing Split → Open Review: Rerankers → Open
Some docs indexed but never surface Pattern: Vectorstore Fragmentation → Open
Two unrelated docs blended in one answer Pattern: Symbolic Constraint Unlock (SCU) → Open

Minimal setup checklist for any LlamaIndex pipeline

Warm-up fence before query engine Ensure index hash and vectorstore state are valid. If not, retry with capped backoff. Spec: Bootstrap Ordering
Idempotency key Compute dedupe_key = sha256(doc_id + rev + index_hash). Drop duplicates at ingestion.
Retriever output contract Require fields: snippet_id, section_id, source_url, offsets, tokens. Enforce cite-then-explain. Specs: Data Contracts · Retrieval Traceability
Observability probes Log ΔS(question, retrieved) and λ transitions at each step. Alert if ΔS ≥ 0.60 or λ flips divergent. Overview: RAG Architecture & Recovery
Concurrency guard One writer per index. Use locks or queue mode. Fix: Deployment Deadlock
Eval before publish Coverage ≥ 0.70 and ΔS ≤ 0.45 required. Eval: RAG Precision/Recall

Copy-paste prompt for LlamaIndex Query Engine

I uploaded TXT OS and WFGY Problem Map files.
This retriever produced {k} docs with fields {snippet_id, section_id, source_url, offsets}.

Steps:

1. Enforce cite-then-explain. If citations missing, fail fast and suggest fix.
2. If ΔS(question, retrieved) ≥ 0.60, propose minimal structural fix referencing:
   retrieval-playbook, retrieval-traceability, data-contracts, rerankers.
3. Return JSON plan:
   { "citations": [...], "answer": "...", "λ_state": "...", "ΔS": 0.xx, "next_fix": "..." }

Common LlamaIndex gotchas

Too many retrievers chained without λ check Add λ variance clamp. Reject divergent paths.
Index rebuild silently drops sections Enforce contracts and log ΔS across ingestion runs.
Async queries race against ingestion Add warm-up fence and bootstrap ordering.
Chunk drift from mismatched parsers Normalize with section detection. See: Section Detection

When to escalate

ΔS stays ≥ 0.60 even after chunking and retriever fixes → Rebuild vectorstore with explicit metric and normalization. Spec: Retrieval Playbook
Identical queries yield inconsistent answers → Check memory drift and version skew. Spec: Context Drift

🔗 Quick-Start Downloads

Tool	Link	3-Step Setup
WFGY 1.0 PDF	Engine Paper	1) Download · 2) Upload to LLM · 3) Ask “Use WFGY to fix my automation bug”
TXT OS	TXTOS.txt	1) Download · 2) Paste into LLM · 3) Type “hello world”

🧭 Explore More

Module	Description	Link
WFGY Core	WFGY 2.0 engine is live: full symbolic reasoning architecture and math stack	View →
Problem Map 1.0	Initial 16-mode diagnostic and symbolic fix framework	View →
Problem Map 2.0	RAG-focused failure tree, modular fixes, and pipelines	View →
Semantic Clinic Index	Expanded failure catalog: prompt injection, memory bugs, logic drift	View →
Semantic Blueprint	Layer-based symbolic reasoning & semantic modulations	View →
Benchmark vs GPT-5	Stress test GPT-5 with full WFGY reasoning suite	View →
🧙‍♂️ Starter Village 🏡	New here? Lost in symbols? Click here and let the wizard guide you through	Start →

👑 Early Stargazers: See the Hall of Fame —
⭐ WFGY Engine 2.0 is already unlocked. ⭐ Star the repo to help others discover it and unlock more on the Unlock Board.

8.6 KiB Raw Blame History