LlamaIndex Guardrails and Patterns

🧭 Quick Return to Map

You are in a sub-page of Automation Platforms.
To reorient, go back here:

Automation Platforms — stabilize no-code workflows and integrations

WFGY Global Fix Map — main Emergency Room, 300+ structured fixes

WFGY Problem Map 1.0 — 16 reproducible failure modes

Think of this page as a desk within a ward.
If you need the full triage and all prescriptions, return to the Emergency Room lobby.

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	Canonical framework entry point	View
Problem Map	Diagnostic map and navigation hub	View
Tension Universe Experiments	MVP experiment field	View
Recognition	Where WFGY is referenced or adopted	View
AI Guide	Anti-hallucination reading protocol for tools	View

If this repository helps, starring it improves discovery for other builders.

7.2 KiB Raw Blame History