agentsope/SkillAlchemy / skills/agentsop-llamaindex
agentsop-llamaindex
VerifiedOperating-system distillation of LlamaIndex — the leading RAG / document-agent framework. Activate when the calling agent must build, debug, harden, or evaluate a Retrieval-Augmented Generation pipeline over unstructured/private data, decide between RAG primitives (Index types, retrievers, query engines, routers, agents), or pick LlamaIndex vs LangChain / Haystack / raw vector store for a coding task. Encodes the 5-layer mental model (Documents → Nodes → Indices → Retrievers → Query Engines / Response Synthesizers), the canonical RAG bootstrap SOP from baseline `VectorStoreIndex` through hybrid + reranker + eval-loop hardening, the official 13-failure-mode checklist, and 5 dilemma cases distilled from docs, GitHub issues, and 2025 production post-mortems.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 1.1 KB |
| SKILL.md | skill md | 25.6 KB |
| intermediate/operation_candidates.json | config | 7.0 KB |
| references/R1-architecture.md | markdown | 8.7 KB |
| references/R2-sop-workflow.md | markdown | 8.9 KB |
| references/R3-dilemma-cases.md | markdown | 14.3 KB |
| references/R4-anti-patterns.md | markdown | 9.9 KB |
| references/R5-ecosystem-context.md | markdown | 8.2 KB |
references/R1-architecture.md
View on GitHub# R1 · LlamaIndex Architecture & Mental Model
## 0. One-sentence framing
LlamaIndex is not a "vector DB wrapper" and not a "general agent framework". It is a **data framework whose central abstraction is the Index** — a queryable intermediate representation that sits between raw private data and an LLM. The whole API surface is structured to make every step of that pipeline a swappable, observable object.
> "LlamaIndex helps you ingest, transform, index, retrieve, and synthesize answers from your own data across many sources." — `developers.llamaindex.ai/python/framework/`
## 1. The 5-layer mental model
```
Documents
↓ (chunking / parsing / metadata extraction)
Nodes
↓ (embedding / structuring)
Index ← the first-class object
↓ (retriever mode, top-k, filters, reranker)
Retriever
↓ (query transformation, fusion, recursion)
Query Engine
↓ (LLM call, refine / tree_summarize / compact)
Response Synthesizer
↓
Response
```
Source: `developers.llamaindex.ai/python/framework/` and the high-level concepts guide; matches the architecture description repeated in every "Getting Started" doc and reaffirmed by 2025 walkthroughs (e.g., `medium.com/@gautsoni/llamaindex-for-beginners-2025-...`).
### Why 5 layers and not 2?
Most homemade RAGs collapse to "chunk → embed → top-k → LLM". LlamaIndex deliberately splits this into 5 because **each layer has its own failure mode and its own optimization knob** (see `R4-anti-patterns.md` for the failure-mode checklist that maps almost 1:1 onto these layers).
| Layer | Failure when missing | LlamaIndex knob |
|---|---|---|
| Documents | Garbage-in: tables/figures lost, boilerplate kept | `LlamaParse`, custom Readers, metadata extractors |
| Nodes | Wrong chunk granularity | `NodeParser` / `SentenceSplitter` / `HierarchicalNodeParser` |
| Index | Wrong retrieval primitive for the task | `VectorStoreIndex` / `SummaryIndex` / `PropertyGraphIndex` / ... |
| Retriever | Top-k too narrow, no rerank, no hybrid | `top_k`, `BM25Retriever`, `QueryFusionRetriever`, postprocessors |
| Response Synthesizer | Context overflow, "lost in the middle" | `refine` / `tree_summarize` / `compact` modes |
## 2. What is a Node, really?
A `Node` is **not** "a chunk of text". It is a typed object that carries:
- `text` (the chunk)
- `metadata` (filterable key-value, propagated from the parent Document)
- `relationships` (PREVIOUS / NEXT / PARENT / CHILD links to other nodes — this is what enables AutoMergingRetriever and SentenceWindow)
- `embedding` (lazy; filled when the Index requires it)
- `id_` and `ref_doc_id` (lifecycle / deduplication keys)
> "Indexes store data in Node objects, which represent chunks of the original documents." — homepage docs.
The relationships field is the often-missed bit: LlamaIndex's advanced retrievers (Recursive, AutoMerging, Sentence-Window) rely on it. A Node is therefore better thought of as **a node in a graph of chunks**, not a row in a vector table. This is what differentiates LlamaIndex from a pure vector-store SDK.
## 3. Index types: what changes between them
From `developers.llamaindex.ai/python/framework/module_guides/indexing/index_guide/`:
| Index | Storage shape | Retrieval | When |
|---|---|---|---|
| **VectorStoreIndex** | Nodes + embeddings in a vector store | Top-k cosine/dot similarity | Default. Semantic Q&A over chunks. ~90% of use cases. |
| **SummaryIndex** (formerly ListIndex) | Nodes in an ordered list (no embeddings required) | Returns **all** nodes (or top-k via optional embedding) | Summarisation; small corpus; "what does this whole doc say?" |
| **TreeIndex** | Hierarchical LLM-built summaries | Traverses root→leaf with `child_branch_factor` | Tree-structured content, progressive zoom-in |
| **KeywordTableIndex** | Keyword → node mapping (LLM-extracted) | Keyword overlap | Keyword-heavy queries, no embeddings budget |
| **KnowledgeGraphIndex / PropertyGraphIndex** | Triples (subj, pred, obj) ± embeddings | Keyword + synonym + vector hybrid over triples | Multi-hop reasoning, entity relationships |
| **DocumentSummaryIndex** | Per-doc LLM summary + node refs | Summary→doc routing then chunk retrieval | Mixed-collection corpora, document-level routing |
### The strategic implication
These are **not interchangeable** — `SummaryIndex` answers "summarize this report" cheaply (no embeddings to build, but N LLM calls at query time) where `VectorStoreIndex` would be wrong (it can't see the whole doc). Hence `RouterQueryEngine` (R2 / R3) — a router over multiple indices is often the right top-level shape.
## 4. Retriever vs Query Engine vs Response Synthesizer
A confusion source for users. Concretely:
- **Retriever** returns `List[NodeWithScore]`. No LLM call. Pure retrieval.
- **Response Synthesizer** takes nodes + query → string. This is where the LLM lives (refine / tree_summarize / compact / accumulate modes).
- **Query Engine** = Retriever + (optional postprocessors / rerankers) + Response Synthesizer, bundled as one `.query()` interface. It is the "facade".
Why split them? So you can:
1. Test retrieval quality without burning LLM tokens (use Retriever + RetrieverEvaluator).
2. Swap the synthesizer (e.g. `tree_summarize` for long contexts) without touching retrieval.
3. Insert NodePostprocessors (rerankers, time-decay, metadata replacement for sentence-window) between the two cleanly.
Cited at `developers.llamaindex.ai/python/framework/module_guides/deploying/query_engine/` (Streaming guide and Query Engine module guide).
## 5. Settings (the Global Config Singleton)
Since v0.10, the global `Settings` object replaces the deprecated `ServiceContext`:
```python
from llama_index.core import Settings
Settings.llm = Ollama(model="llama2")
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")
Settings.chunk_size = 1024
```
Crucial property: **lazy instantiation** — modules only load LLM/embed if they need them. Old `ServiceContext` forced eager loading and was a notorious source of double-config bugs (`docs.llamaindex.ai/.../service_context_migration/`). Failure modes #4 and #5 in the official checklist (embedding-model mismatch, config drift) are precisely caused by *not* using a single global Settings.
## 6. Workflows: the 2025 successor to QueryPipeline
LlamaIndex shipped `QueryPipeline` as a declarative DAG in 2024. It was deprecated within a year because **agentic logic needs cycles**, which DAGs forbid. The replacement (`Workflows 1.0`, announced 2025-06-30) is event-driven: every step subscribes to and emits events, naturally supporting loops, branching, retries.
> "A fundamental aspect of DAGs is that they are acyclic with no loops, but in a world that's more agentic, the inability to perform loops in an AI application's logic is simply unacceptable." — `llamaindex.ai/blog/announcing-workflows-1-0-...`
For any new project in 2025+, the canonical orchestration primitive is **Workflows**, not QueryPipeline. Agents (FunctionAgent / ReActAgent) are themselves built on top of Workflows.
## 7. What's the *operating system* under the architecture?
Three principles, abstracted from the docs:
1. **Indices are first-class.** "Index" is a noun in LlamaIndex's grammar, not a verb. You pick the right Index for the task (`VectorStoreIndex` ≠ `SummaryIndex` ≠ `PropertyGraphIndex`). LangChain by contrast treats retrieval as a verb (`.as_retriever()` on a vector store).
2. **Every transform is inspectable.** Documents, Nodes, NodeWithScore, Response — each layer hands off a typed object you can print, log, replay. This is why observability is a tier-1 concern (failure #12) rather than a bolt-on.
3. **Chunking is architecture, not preprocessing.** Node-parsers (Hierarchical, Sentence-Window) build *relationships* between chunks at ingestion time so advanced retrievers can exploit them. The mental flip: don't think "split into chunks", think "build a chunk-graph".
## 8. Source list (R1)
- `https://developers.llamaindex.ai/python/framework/`
- `https://developers.llamaindex.ai/python/framework/module_guides/indexing/index_guide/`
- `https://developers.llamaindex.ai/python/framework/module_guides/deploying/query_engine/`
- `https://docs.llamaindex.ai/en/stable/module_guides/supporting_modules/service_context_migration/`
- `https://www.llamaindex.ai/blog/announcing-workflows-1-0-a-lightweight-framework-for-agentic-systems`
- `https://github.com/run-llama/llama_index` (README)
- `https://medium.com/@gautsoni/llamaindex-for-beginners-2025-a-complete-guide-to-building-rag-apps-from-zero-to-production-cb15ad290fe0`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |