llamaindex

---
name: llamaindex
description: >-
license: MIT
---

# LlamaIndex Expert Skill

LlamaIndex is an MIT-licensed Python framework for building LLM applications over your data. In 2026, it has evolved from a RAG indexing library into an event-driven workflow framework with integrated production runtime (llama-deploy), agent orchestration (AgentWorkflow), knowledge graph construction (PropertyGraphIndex), and OpenTelemetry-native observability.

The framework is organized around seven core primitives: **Reader** (data loaders), **Document/Node** (chunked content model), **Index** (data structures over Nodes), **Retriever** (relevant Node selection), **Query Engine** (retriever + synthesis), **Agent** (LLM with tools), and **Workflow** (event-driven orchestration).

## Key Principles

> These principles govern every decision when building with LlamaIndex. Read them before proceeding to the reference guides.

1. **Decouple retrieval chunks from synthesis chunks.** The embedding representation that retrieves well differs from the context representation that generates well. Use `SentenceWindowNodeParser` + `MetadataReplacementNodePostProcessor` for this pattern.
2. **Rerank before you generate.** Hybrid retrieval + reranker is the minimum viable production RAG configuration.
3. **Agents are Workflows.** `FunctionAgent` and `AgentWorkflow` are pre-configured Workflows. Drop to raw `Workflow` when you need custom control flow.
4. **Graphs are not just vector stores.** `PropertyGraphIndex` adds structural path traversal that vector similarity cannot provide — combine both for maximum retrieval quality.
5. **Evaluate in the same process.** Span-attached evaluation preserves the connection between the output and the retrieval context that produced it.

## Where to Start

The pipeline has 9 phases from Ingest to Deploy. If you're joining mid-stream with existing work, find your entry point:

| You already have... | Start at phase | What to do |
|---|---|---|
| Nothing — blank project | **Ingest** | Set up data loading, then proceed through the full pipeline |
| Documents in a directory | **Chunk** | Choose a chunking strategy, build your index |
| A working vector index | **Retrieve** | Add hybrid search, reranking, metadata filters |
| An existing RAG pipeline to harden | **Deploy** | Add observability, llama-deploy, production debugging |
| A need to measure and improve quality | **Evaluate** | Set up evaluators, ParamTuner, span-attached scoring |
| Nothing — comparing frameworks | See Framework Routing Guide | Don't start the pipeline — pick the right tool first |

## Pipeline Mode

Different tasks need different levels of rigor. Match your scope to a mode:

| Mode | When | Phases to run | Skip |
|------|------|---------------|------|
| **Quick** | Single query, one source, exploration | Ingest → Chunk → Index → Retrieve | Reranking, metadata filters, observability, evaluation |
| **Full** | Production RAG, multiple sources, compliance | Ingest → Chunk → Index → Retrieve → Agent/Workflow → Deploy → Evaluate | Nothing — run all phases |
| **Evaluate** | Benchmarking, regression testing | Ingest → Chunk → Index → Evaluate | Retrieve, Agent, Workflow, Deploy (run offline) |
| **Graph** | Knowledge graph construction | Ingest → Chunk → Graph → Retrieve | Agent, Workflow, Deploy (query via graph index directly) |

Rule of thumb: if you're shipping to users, run Full mode. If you're exploring, run Quick. If you're measuring, run Evaluate.

## Quick Reference

| Phase | Task | Approach | Reference |
|-------|------|----------|-----------|
| Ingest | Load data | `SimpleDirectoryReader("./data").load_data()` | `references/architecture.md` |
| Chunk | Parse documents into nodes | `SentenceSplitter(chunk_size=1024)` | `references/rag-strategies.md` |
| Index | Build vector index | `VectorStoreIndex.from_documents(docs)` | `references/rag-strategies.md` |
| Retrieve | Hybrid search + rerank | `BM25Retriever` + `CohereRerank` | `references/rag-strategies.md` |
| Agent | Multi-agent orchestration | `AgentWorkflow(agents=[...])` | `references/agent-patterns.md` |
| Workflow | Event-driven pipeline | `class MyFlow(Workflow): @step` | `references/workflows.md` |
| Graph | Knowledge graph | `PropertyGraphIndex.from_documents(docs)` | `references/property-graph-index.md` |
| Evaluate | RAG evaluation | `FaithfulnessEvaluator().evaluate_response(...)` | `references/evaluation-observability.md` |
| Deploy | Production deployment | `deploy_workflow(workflow=MyFlow())` | `references/production-deployment.md` |

## When to Use This Skill

Load this skill any time you are:
- Building a RAG pipeline over enterprise or personal data
- Comparing LlamaIndex with LangChain, Haystack, or DSPy
- Designing multi-agent systems with handoff between specialist agents
- Deploying an LLM application to production with observability
- Constructing knowledge graphs from unstructured documents
- Debugging common LlamaIndex failures (retrieval miss, handoff bug, async issues)

## When NOT to Use LlamaIndex — Framework Routing Guide

This skill is part of a portfolio of framework skills. When deciding which framework fits, use this routing table:

| Scenario | Reach for | Why |
|----------|-----------|-----|
| I have documents I need to query | **LlamaIndex** | Data ingestion, hybrid retrieval, reranking, and knowledge graphs are first-class primitives |
| I have agents I need to orchestrate | **LangGraph** | State-machine semantics, time-travel debugging, and human-in-the-loop pauses are the core design |
| I have a tool I need to wrap as an agent | **PydanticAI** | Type-safe agent definitions with dependency injection, minimal abstraction over LLM calls |
| Data-heavy RAG over PDFs, SQL, Slack, 200+ sources | **LlamaIndex** | LlamaHub connectors, LlamaParse for documents, hybrid retrieval out of the box |
| Complex multi-agent state machines with checkpoints | **LangGraph** | Graph topology control — supervisor, subgraphs, hierarchical teams, built-in checkpointer |
| Agent-centric app where type safety matters more than data pipelines | **PydanticAI** | Agents as Pydantic models, DI, structured outputs — the data layer is your code |
| Document parsing quality matters (tables, charts, handwriting) | **LlamaIndex** | LlamaParse is purpose-built for this |
| Production NLP search pipelines | **Haystack** | Pipeline composition model is more mature for search-specific workloads |
| Optimization-driven prompt programming | **DSPy** | Compiled prompt programs, not retrieval pipelines |

## Reference Files

| Reference | Load when | File |
|-----------|-----------|------|
| Core Architecture | Understanding the 7 primitives, Settings, data flow | `references/architecture.md` |
| RAG Strategies | Building RAG pipelines from basic to advanced | `references/rag-strategies.md` |
| Agent Patterns | Multi-agent orchestration with AgentWorkflow | `references/agent-patterns.md` |
| Workflows | Event-driven step composition and durable execution | `references/workflows.md` |
| Production & Deployment | llama-deploy, debugging, failure modes | `references/production-deployment.md` |
| Property Graph Index | Knowledge graph construction and hybrid retrieval | `references/property-graph-index.md` |
| Evaluation & Observability | Metrics, tracing, span-attached scoring | `references/evaluation-observability.md` |
| Integration Ecosystem | Vector stores, LlamaHub, LlamaParse, ecosystem | `references/integration-ecosystem.md` |
| FAQ & Troubleshooting | Common errors and their fixes | `references/faq-and-troubleshooting.md` |
| Worked RAG Example | Complete end-to-end pipeline from ingest to deploy | `references/example-rag-pipeline.md` |
| Evaluation Workflow | ParamTuner, evaluators, batch scoring, best practices | `references/evaluation-workflow.md` |

## Template Files

| Template | When to use | File |
|----------|-------------|------|
| Basic RAG | Single-source query, getting started | `templates/basic-rag.py` |
| Agentic RAG | Multi-source data with agent routing | `templates/agentic-rag.py` |
| Custom Workflow | Custom control flow, branching logic | `templates/custom-workflow.py` |
| Production Deploy | Wrapping a workflow as a microservice | `templates/production-deploy.py` |

## Scripts

| Script | Purpose | File |
|--------|---------|------|
| check-setup | Verify LlamaIndex installation and configuration | `scripts/check-setup.py` |

## Troubleshooting — Structured Recovery Guide

When something goes wrong, find your symptom and follow the recovery path:

### Retrieval & Answer Quality

| Symptom | Likely cause | Immediate fix | Permanent fix | Reference |
|---------|-------------|---------------|---------------|-----------|
| Answers are poor or hallucinated | No reranker on hybrid retrieval | Add `CohereRerank(top_n=5)` as `node_postprocessor` | Reranking is mandatory for any production RAG | `references/rag-strategies.md` |
| Retrieval misses obvious content | Default chunking breaks semantics | Switch to `SemanticSplitterNodeParser(breakpoint_percentile_threshold=95)` | Tune chunk size with ParamTuner | `references/rag-strategies.md` |
| Wrong tenant's data returned | Missing metadata filters | Add `MetadataFilters(filters=[ExactMatchFilter(key="tenant_id", ...)])` | Always wire metadata filters at retriever level | `references/rag-strategies.md` |
| Only one type of query works well | Single retrieval strategy | Combine BM25 + vector via hybrid retriever | Add RouterQueryEngine for query-type routing | `references/rag-strategies.md` |

### Agent & Workflow Failures

| Symptom | Likely cause | Immediate fix | Permanent fix | Reference |
|---------|-------------|---------------|---------------|-----------|
| Agent waits silently after handoff | AgentWorkflow handoff bug | Extend `FunctionAgent.take_step` to re-locate last user message | Apply the handoff fix on all production agents | `references/agent-patterns.md` |
| Workflow doesn't run | Forgot `await` | Add `await` before `w.run(...)` and all step calls | All step methods are async coroutines | `references/workflows.md` |
| Step executes but result is lost | State not persisted | Use `ctx.store.edit_state()` for shared state | Only `ctx.store` survives across steps | `references/workflows.md` |
| Crash loses all progress | No checkpoint snapshots | Add `Context.to_dict()` save on step completion | Durable workflows need explicit checkpointing | `references/workflows.md` |

### Deployment & Observability

| Symptom | Likely cause | Immediate fix | Permanent fix | Reference |
|---------|-------------|---------------|---------------|-----------|
| llama-deploy deployed but requests time out | Redis not running | Start `redis-server` | Redis is mandatory — control plane won't route without it | `references/production-deployment.md` |
| Spans missing in observability UI | Instrumentation called too late | Move `instrument()` call before workflow instantiation | Always instrument before creating any Workflow object | `references/production-deployment.md` |
| Wrong data returned (cross-tenant) | Missing metadata filters | Add tenant filter to all retrievers | Filter at retriever level, not in post-processing | `references/production-deployment.md` |

### Recovery Workflow

For any failure, follow this cycle:
1. **Identify the symptom** from the tables above
2. **Apply the immediate fix** — this gets you running
3. **Implement the permanent fix** — this prevents recurrence
4. **Verify with evaluation** — run `FaithfulnessEvaluator` on a held-out query set
5. **Document the fix** — add the root cause to `references/faq-and-troubleshooting.md`