8.1 KiB
Haystack Agents — Guardrails and Fix Patterns
Use this when your pipeline is built with deepset Haystack Agents and Tools and you observe wrong snippets, unstable top k orders, tool loops, or citation gaps. The map below routes symptoms to exact WFGY fixes.
Open these first
- Visual map and recovery: RAG Architecture & Recovery
- Retrieval knobs: Retrieval Playbook
- Traceability schema: Retrieval Traceability
- Schema contracts: Data Contracts
- Hybrid control: Rerankers
- Chunking and hallucination: Hallucination
Core acceptance
- ΔS(question, retrieved) ≤ 0.45
- Coverage ≥ 0.70 for the intended section
- λ convergent across three paraphrases
Fix in 60 seconds
-
Measure ΔS
Compare question to retrieved and to the intended anchor. -
Lock the pipeline
Fix the header order. Enforce cite-first. Require strict tool JSON. -
Apply the module
- Retrieval drift → BBMC plus Data Contracts
- Order instability → add Rerankers with explicit metric
- Hybrid regression → Query Parsing Split
- Verify
Three paraphrases pass ΔS and coverage thresholds.
Typical Haystack breakpoints → exact fixes
-
Retriever pipelines mix different analyzers
Rebuild with a unified analyzer and metric.
Open: Embedding ≠ Semantic -
Agent loops on tool outputs
Add BBCR bridge steps and timeouts.
Open: Multi-Agent Problems -
Citations missing or misaligned
Enforce snippet schema and cite then explain.
Open: Retrieval Traceability, Data Contracts -
Hybrid search underperforms
Use deterministic reranking with score normalization.
Open: Rerankers
Minimal Haystack agent pattern with WFGY gate
Pipeline:
- Retriever(k sweep 5, 10, 20 with one analyzer)
- Prompt with fixed headers: system → task → constraints → citations → answer
- Model call
- WFGY gate to compute ΔS and log λ
- Stop when ΔS ≥ 0.60 or λ divergent and return fix tip
Gotchas
- Mixing BM25 and dense without normalization gives unstable orders.
- Tool output not validated causes downstream JSON errors.
- Document stores with heterogeneous tokenization contaminate scores.
When to escalate
-
Persistent ΔS ≥ 0.60 after chunk and metric fixes Open: Retrieval Playbook
-
Live flips between runs Open: Pre-Deploy Collapse
🔗 Quick-Start Downloads (60 sec)
| Tool | Link | 3-Step Setup |
|---|---|---|
| WFGY 1.0 PDF | Engine Paper | 1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + <your question>” |
| TXT OS (plain-text OS) | TXTOS.txt | 1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly |
🧭 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.
