# LlamaIndex Admin & Architecture Guide

This guide is for the engineers, architects, and platform operators who **deploy, integrate, extend, or contribute to** LlamaIndex. It documents the framework's architecture, the contract that makes its 300+ integrations interchangeable, the configuration surface, storage and instrumentation internals, the security model, and the monorepo's build and release tooling.

For day-to-day application usage (loading data, building indexes, querying), see the companion **User Guide**.

---

## 1. Executive Summary

**LlamaIndex** is an open-source Python **data framework for building LLM-powered and agentic applications**. Its job is to connect private/custom data to language models for retrieval-augmented generation (RAG), structured extraction, and tool-using agents.

| Attribute | Value |
|-----------|-------|
| Project | `run-llama/llama_index` |
| Type | Python library / framework (not a service or CLI app) |
| Language | Python (`>=3.10, <4.0`) |
| License | MIT |
| Flagship package version | `llama-index` 0.14.22 |
| Core package | `llama-index-core` (0.14.x) |
| Repository shape | **Monorepo**: 1 core + 1 instrumentation + 1 utils tree + 300+ integration packages |
| Build backend | `hatchling` (per-package), `uv` workspace lockfile |
| Author / maintainers | Jerry Liu and the LlamaIndex team |

**Architectural thesis:** a small, stable **core** defines abstract interfaces for every pluggable concern (LLMs, embeddings, vector stores, readers, tools, storage). Each provider is shipped as an **independently versioned, separately installable package** that subclasses a core interface. Applications depend on core and select only the integrations they need. This is the same "framework core + plugin ecosystem" pattern seen in platforms like Airflow's providers or TanStack's framework adapters.

> [!IMPORTANT]
> The unit you deploy is **your application**, with LlamaIndex as a library dependency. LlamaIndex does not run a server, daemon, or background process of its own. Operational concerns (scaling, networking, secrets) belong to your host application and the external services (vector DBs, LLM APIs) you wire in.

---

## 2. Repository Architecture

### 2.1 Top-level layout

The repository is a `uv`-managed monorepo. The meaningful trees:

```
llama_index/
├── llama-index-core/            # THE FRAMEWORK — abstractions + default implementations
│   └── llama_index/core/
│       ├── schema.py            # Document, Node, TextNode, ImageNode, MediaResource
│       ├── settings.py          # global Settings object (_Settings)
│       ├── constants.py         # default chunk size, top-k, temperature, etc.
│       ├── indices/             # VectorStoreIndex, SummaryIndex, TreeIndex, graph indices
│       ├── readers/             # SimpleDirectoryReader and base reader interfaces
│       ├── llms/, embeddings/   # abstract LLM / embedding interfaces
│       ├── retrievers/, response_synthesizers/, query_engine/
│       ├── storage/             # docstore / index_store / kvstore / chat_store / vector_store
│       ├── instrumentation/     # event + span dispatcher system
│       ├── rate_limiter.py      # token-bucket & sliding-window limiters
│       └── service_context.py   # DEPRECATED shim that raises pointing to Settings
├── llama-index-integrations/    # 300+ plugin packages, grouped by category
│   ├── llms/llama-index-llms-*
│   ├── embeddings/llama-index-embeddings-*
│   ├── vector_stores/llama-index-vector-stores-*
│   ├── readers/llama-index-readers-*
│   ├── tools/llama-index-tools-*
│   ├── postprocessor/llama-index-postprocessor-*
│   ├── graph_stores/, storage/, agent/, node_parser/, ...
├── llama-index-instrumentation/ # standalone instrumentation package
├── llama-index-utils/           # shared utility sub-packages (azure, huggingface, qianfan, ...)
├── llama-dev/                   # contributor CLI for managing the monorepo (Click)
├── docs/                        # MkDocs Material site + auto-generated API reference
├── scripts/                     # maintenance scripts
├── pyproject.toml               # the umbrella `llama-index` starter package
└── uv.lock                      # workspace lockfile
```

> [!NOTE]
> The file tree is large (~10,000 files) because each of the 300+ integrations is a full Python package with its own `pyproject.toml`, source, tests, and examples. The *conceptual* surface is much smaller: core defines the interfaces; integrations are repetitive implementations of them.

### 2.2 The namespace contract

LlamaIndex uses **PEP 420 namespace packages** under the shared `llama_index` namespace. This is what lets dozens of independently published packages cohabit one import root:

- `llama_index.core.*` → ships in `llama-index-core`.
- `llama_index.<category>.<provider>` → ships in `llama-index-<category>-<provider>` (e.g. `llama_index.llms.openai` ← `llama-index-llms-openai`).

The presence or absence of `core` in an import path tells you, unambiguously, whether code is framework or integration.

### 2.3 The two distribution packages

| Package | `pip install` | Contents | Audience |
|---------|---------------|----------|----------|
| `llama-index` (umbrella) | `pip install llama-index` | core + `llama-index-llms-openai` + `llama-index-embeddings-openai` + `nltk` | Quick start |
| `llama-index-core` | `pip install llama-index-core` | Framework only | Production, custom stacks |

The umbrella package's declared dependencies (from `pyproject.toml`):

```toml
dependencies = [
    "llama-index-core>=0.14.22,<0.15.0",
    "llama-index-embeddings-openai>=0.6.0,<0.7",
    "llama-index-llms-openai>=0.7.0,<0.8",
    "nltk>=3.9.3",
]
```

---

## 3. Core Abstractions

The framework's data model and interfaces live in `llama-index-core`. Understanding these is the key to extending the framework.

### 3.1 The schema (data model) — `core/schema.py`

Everything is a Pydantic model rooted at `BaseComponent`, which adds a serialization-stable `class_name` so objects survive round-trips through JSON and storage.

```
BaseComponent (BaseModel)
├── TransformComponent          # base for anything that transforms nodes (parsers, extractors)
├── RelatedNodeInfo             # a typed reference from one node to another
├── BaseNode                    # abstract retrievable unit
│   ├── Node                    # multimodal node (text/image/audio/video resources)
│   ├── TextNode                # text node (backward-compatible)
│   │   ├── ImageNode
│   │   └── IndexNode           # node that points at another object/index
│   └── Document (← Node)       # a source document
│       └── ImageDocument
├── MediaResource               # container for text/binary/path/url media + embeddings
├── NodeWithScore               # a node plus a retrieval relevance score
└── QueryBundle                 # a query string + optional embeddings/images
```

Key design points:

- **Nodes carry relationships.** `NodeRelationship` (`SOURCE`, `PREVIOUS`, `NEXT`, `PARENT`, `CHILD`) lets retrieval reconstruct document order and hierarchy. `SOURCE`/`PREVIOUS`/`NEXT`/`PARENT` map to a single `RelatedNodeInfo`; `CHILD` maps to a list — mismatching these raises a `ValueError`.
- **Metadata visibility is controllable per consumer.** `MetadataMode` (`ALL`, `EMBED`, `LLM`, `NONE`) plus `excluded_embed_metadata_keys` / `excluded_llm_metadata_keys` let you show different metadata to the embedding model versus the LLM versus storage.
- **Multimodality is first-class.** `Node` holds separate `text_resource`, `image_resource`, `audio_resource`, `video_resource` fields, each a `MediaResource`. `MediaResource` auto-base64-encodes binary data and guesses MIME types via the `filetype` library.
- **Hashing is content-derived.** Each node computes a stable `sha256` hash over its content + metadata, enabling change detection and deduplication during ingestion.

### 3.2 Global configuration — `core/settings.py`

`Settings` (an instance of the internal `_Settings`) is a process-wide singleton holding the default `llm`, `embed_model`, `tokenizer`, `node_parser`/`text_splitter`, `callback_manager`, `prompt_helper`, `context_window`, and `num_output`. Components read from `Settings` lazily when not given an explicit object, so setting it once at startup configures the whole pipeline.

Reading `Settings.chunk_size`/`chunk_overlap` proxies to the configured node parser and raises `ValueError("Configured node parser does not have chunk size./overlap.")` if that parser doesn't expose them.

### 3.3 Default constants — `core/constants.py`

These literals define the framework's out-of-the-box behavior and are the authoritative "config reference" for a library that has no runtime config file.

| Constant | Value | Meaning |
|----------|-------|---------|
| `DEFAULT_TEMPERATURE` | `0.1` | LLM sampling temperature |
| `DEFAULT_CONTEXT_WINDOW` | `3900` | Assumed model context (tokens) |
| `DEFAULT_NUM_OUTPUTS` | `256` | Default max output tokens |
| `DEFAULT_NUM_INPUT_FILES` | `10` | Default input file cap |
| `DEFAULT_EMBED_BATCH_SIZE` | `10` | Embedding requests per batch |
| `DEFAULT_CHUNK_SIZE` | `1024` | Node chunk size (tokens) |
| `DEFAULT_CHUNK_OVERLAP` | `20` | Overlap between chunks (tokens) |
| `DEFAULT_SIMILARITY_TOP_K` | `2` | Nodes retrieved per query |
| `DEFAULT_IMAGE_SIMILARITY_TOP_K` | `2` | Image nodes retrieved per query |
| `DEFAULT_EMBEDDING_DIM` | `1536` | Default vector dimension (text-embedding-ada-002) |

LlamaCloud client constants also live here: `DEFAULT_BASE_URL = "https://api.cloud.llamaindex.ai"`, `DEFAULT_APP_URL = "https://cloud.llamaindex.ai"`.

### 3.4 Storage keys

Storage namespacing constants (`VECTOR_STORE_KEY`, `IMAGE_STORE_KEY`, `GRAPH_STORE_KEY`, `INDEX_STORE_KEY`, `DOC_STORE_KEY`, `PG_STORE_KEY`) and serialization markers (`TYPE_KEY = "__type__"`, `DATA_KEY = "__data__"`) define how a `StorageContext` lays out its sub-stores.

---

## 4. The Plugin Contract (Extending LlamaIndex)

The reason 300+ integrations interoperate is that each subclasses a core abstract base class and implements its required methods. To add a new provider you implement the relevant interface; nothing in core changes.

| To add a… | Subclass | Key methods to implement |
|-----------|----------|--------------------------|
| LLM | `llama_index.core.llms.LLM` (via `CustomLLM`) | `complete`/`chat` + streaming + async variants; `metadata` |
| Embedding model | `llama_index.core.base.embeddings.BaseEmbedding` | `_get_text_embedding`, `_get_query_embedding`, async variants |
| Vector store | `llama_index.core.vector_stores.types.BasePydanticVectorStore` | `add`, `delete`, `query` |
| Reader / connector | `llama_index.core.readers.base.BaseReader` | `load_data` |
| Node transform | `llama_index.core.schema.TransformComponent` | `__call__`, `acall` |
| Tool (for agents) | `llama_index.core.tools.BaseTool` | tool metadata + `__call__` |
| Output parser | `llama_index.core.types.BaseOutputParser` | `parse`, `format` |
| Structured program | `llama_index.core.types.BasePydanticProgram` | `__call__`, `acall`, `output_cls` |

Worked examples from the codebase: `AdapterEmbeddingModel(BaseEmbedding)` (embeddings adapter), `ArkEmbedding(BaseEmbedding)`, and the many `*VectorStore(BasePydanticVectorStore)` implementations.

> [!TIP]
> Each integration is a standalone package with its own `pyproject.toml`, tests, and (often) `examples/`. Use the existing package nearest your category as a template — they are deliberately uniform.

### 4.1 The deprecation shim pattern

When core removes a public concept it keeps a stub that fails loudly with a migration pointer rather than silently breaking imports. `ServiceContext` is the canonical example: constructing one raises

```text
ValueError: ServiceContext is deprecated. Use llama_index.settings.Settings instead,
or pass in modules to local functions/methods/interfaces.
```

Deprecated *attributes* (e.g. `extra_info` → `metadata`, `node_info` → `get_node_info`) use the `@deprecated` decorator and emit `DeprecationWarning`.

---

## 5. Instrumentation & Observability

LlamaIndex ships a built-in instrumentation system in `core/instrumentation/` (and the standalone `llama-index-instrumentation` package). It is the integration point for tracing, metrics, and third-party observability tools.

- **Dispatcher / spans.** Modules obtain a dispatcher via `instrument.get_dispatcher(__name__)` and wrap operations with `@dispatcher.span`. `DispatcherSpanMixin` gives any class span support. This is how nested operations (query → retrieve → rerank → synthesize) produce a span tree.
- **Typed events.** `core/instrumentation/events/` defines `BaseEvent` subclasses for every pipeline stage: `QueryStartEvent`/`QueryEndEvent`, `RetrievalStartEvent`/`RetrievalEndEvent`, `ReRankStartEvent`/`ReRankEndEvent`, `AgentRunStepStartEvent`/`AgentRunStepEndEvent`, `ExceptionEvent`. Subscribe a handler to receive these.
- **Global handler hook.** `set_global_handler(...)` (re-exported from the top-level package) wires a third-party callback handler (e.g. Arize Phoenix, Langfuse, W&B, OpenInference) in one call.
- **OpenTelemetry.** `llama-index-observability-otel` bridges the event/span system to OTel.

Observability integrations available as packages include `arize-phoenix`, `langfuse`, `wandb`, `openinference`, `opik`, `literalai`, `agentops`, `honeyhive`, `uptrain`, and `argilla`.

> [!TIP]
> For production, set a global handler at startup and export spans to your APM/observability backend. The span tree makes it possible to attribute latency to retrieval vs. reranking vs. generation — essential for tuning RAG performance.

---

## 6. Rate Limiting

Core ships provider-agnostic rate limiters in `core/rate_limiter.py` so you can throttle LLM and embedding calls to stay within provider quotas. They can be **shared** across multiple LLM/embedding objects that hit the same endpoint, enforcing one global budget.

| Class | Strategy | When to use |
|-------|----------|-------------|
| `TokenBucketRateLimiter` (alias `RateLimiter`) | Token bucket: allows an initial burst, then smooths to the sustained rate | Matches most provider rate limits |
| `SlidingWindowRateLimiter` | Strict rolling 60-second window, optional burst headroom | APIs that enforce hard per-minute caps |
| `BaseRateLimiter` | Abstract base (`acquire`, `async_acquire`) | Custom strategies (e.g. distributed/Redis-backed) |

Both support requests-per-minute (RPM) and tokens-per-minute (TPM) limits and expose synchronous `acquire()` and asynchronous `async_acquire()`.

```python
from llama_index.core.rate_limiter import TokenBucketRateLimiter

# one shared budget for an LLM + embedding hitting the same API
limiter = TokenBucketRateLimiter(requests_per_minute=30)
```

> [!CAUTION]
> `SlidingWindowRateLimiter` raises `ValueError("At least one of requests_per_minute or tokens_per_minute must be set.")` if you construct it with neither limit. Always set at least one.

---

## 7. Storage Architecture

A `StorageContext` aggregates the persistent stores an index needs. Each sub-store is an abstract interface in core with many backing implementations as integration packages.

| Sub-store | Holds | Core key | Integration packages |
|-----------|-------|----------|----------------------|
| Document store (`docstore`) | The nodes/documents | `DOC_STORE_KEY` | redis, postgres, mongodb, dynamodb, firestore, couchbase, azure, gel, tablestore, duckdb |
| Index store (`index_store`) | Index metadata/structs | `INDEX_STORE_KEY` | same backends as docstore |
| Vector store (`vector_store`) | Embedding vectors | `VECTOR_STORE_KEY` | qdrant, pinecone, chroma, milvus, weaviate, postgres (pgvector), redis, elasticsearch, faiss, lancedb, azureaisearch, mongodb, and 80+ more |
| KV store (`kvstore`) | Low-level key/value substrate under the above | — | redis, postgres, mongodb, s3, dynamodb, azure, couchbase, duckdb |
| Chat store (`chat_store`) | Conversation history | — | redis, postgres, mongodb, dynamodb, sqlite, upstash, azure |

```python
from llama_index.core import StorageContext

storage_context = StorageContext.from_defaults(
    vector_store=my_vector_store,   # external vector DB
    # docstore / index_store default to in-memory if not supplied
)
```

Local persistence (`storage_context.persist(persist_dir=...)`) serializes the in-memory stores to JSON on disk; external stores persist in their own databases and are reconnected rather than reloaded.

> [!IMPORTANT]
> The embedding model used at index build time is implicitly baked into the stored vectors. Reloading or reconnecting an index with a *different* embedding model yields meaningless similarity. Pin the embedding model alongside the store.

---

## 8. Security Analysis

### 8.1 Threat model (from `SECURITY.md`)

LlamaIndex is **a library intended to run inside a trusted execution environment** — server-side backends, scheduled jobs, local scripts. When you embed it in a network-facing service you create a new attack surface that is **explicitly out of scope** for the project. Specifically, the hosting application is responsible for:

- Validation and sanitization of **all** user-supplied input (text, URLs, file paths, model parameters).
- Authentication, authorization, rate limiting, and other web security controls.
- Size limiting and content-type validation before data reaches the library.

> [!WARNING]
> Do not treat LlamaIndex as a security boundary. If untrusted users can influence query text, file paths, or tool arguments, your application must sanitize those inputs. Tool-using agents in particular can be steered by prompt injection in retrieved content — constrain which tools an agent can call and validate tool outputs.

### 8.2 Vulnerability scope & disclosure

Bug bounties (via the Huntr platform) cover only the umbrella `llama-index` package and its first-degree dependencies: `llama-index-core`, `llama-index-embeddings-openai`, `llama-index-llms-openai`, `llama-index-cli`. Any integration that is not a first-degree dependency is out of bounty scope but can still be responsibly disclosed through GitHub's "Report a vulnerability" flow.

### 8.3 Secrets handling

Integrations read provider credentials from environment variables (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and per-provider keys such as `COHERE_API_KEY`, `BOX_CLIENT_SECRET`, `NEO4J_PASSWORD`). LlamaIndex does not manage a secret store of its own.

- Never hard-code keys in source; inject them via environment or your platform's secret manager.
- Be mindful that document **metadata** is sent to the LLM and embedding APIs by default — use `excluded_llm_metadata_keys` / `excluded_embed_metadata_keys` to keep sensitive fields (PII, internal IDs) out of provider requests.

### 8.4 Untrusted readers and path handling

Data connectors fetch from external systems and the local filesystem. Treat reader inputs as untrusted: a reader pointed at attacker-controlled paths or URLs can read or write unintended locations. (For example, a path-traversal class of issue has been reported against a cloud-storage reader where downloaded files could be written outside the target directory.) When you accept reader targets from users, canonicalize and allow-list paths and validate URLs before loading.

### 8.5 Build-asset provenance

`llama-index-core` ships a `_static` folder containing cached `nltk` and `tiktoken` data so it runs in disk-restricted environments. These assets are signed with GitHub's `attest-build-provenance` action and can be independently verified:

```bash
STATIC_DIR="venv/lib/python3.13/site-packages/llama_index/core/_static"
REPO="run-llama/llama_index"
find "$STATIC_DIR" -type f | while read -r file; do
    gh attestation verify "$file" -R "$REPO" || echo "Failed to verify: $file"
done
```

### 8.6 Supply-chain considerations

Because an application typically installs many independently versioned integration packages, your dependency surface is large. Pin versions, audit which integrations you actually need, and prefer the customized install (`llama-index-core` + explicit integrations) over the broad starter bundle in production to minimize transitive dependencies.

---

## 9. Build, Release & Contributor Tooling

### 9.1 `llama-dev` — the monorepo CLI

`llama-dev` (in `llama-dev/`, built on Click) is the **contributor** tool for operating across the 300+ packages. It is *not* an end-user command. Top-level options: `--repo-root` (defaults to `.`), `--debug`.

| Command | Purpose | Notable options |
|---------|---------|-----------------|
| `llama-dev pkg bump <pkgs>` | Bump package version(s) | `--all`, `--version-type` (default patch), `--dry-run` |
| `llama-dev pkg info <pkgs>` | Show package info | `--all`, `--json` |
| `llama-dev pkg cmd-exec <pkgs>` | Run a command across packages | `--cmd "..."`, `--all`, `--fail-fast`, `--silent` |

These commands operate on directories recognized as LlamaIndex packages; targeting a non-package path raises `UsageError("<path> is not a path to a LlamaIndex package")`, and invoking without a target or `--all` raises `UsageError("Either specify package name(s) or use the --all flag")`.

### 9.2 Build system

- **Per-package build backend:** `hatchling`.
- **Workspace management:** `uv` with a root `uv.lock`. A custom PyPI index (`nvidia-pypi`, `https://pypi.nvidia.com`) is configured for NVIDIA-dependent integrations.
- **Umbrella wheel mapping:** `pyproject.toml` maps `_llama-index/llama_index` → `llama_index` in the built wheel/sdist.

### 9.3 Code quality gates (`.pre-commit-config.yaml`)

| Tool | Role |
|------|------|
| `ruff` (v0.11.x) + `ruff-format` | Lint + format (target `py312`) |
| `mypy` (v1.x) | Static typing (`--disallow-untyped-defs`, namespace packages) |
| `black` (docs/examples only) | Format docstrings/notebooks at 79 cols |
| `blacken-docs` | Format code blocks in rst/markdown |
| `codespell` | Spell-check |
| `prettier` | Format non-Python files |
| `nb-clean` | Strip notebook noise |
| `toml-sort` | Keep `pyproject.toml` files tidy |
| pre-commit-hooks | `detect-private-key`, `check-yaml/toml`, merge-conflict, EOF fixers |

> [!NOTE]
> The `detect-private-key` pre-commit hook is a meaningful supply-chain control for a repo this size — it blocks accidental key commits across hundreds of contributor PRs.

### 9.4 Testing

Tests use `pytest` with `pytest-asyncio` and `pytest-mock`. Each integration package carries its own test suite; the `llama-dev pkg cmd-exec --all --cmd "pytest"` pattern is how CI fans tests out across packages. Test doubles like `MockEmbedding` (exported from core) let you exercise pipelines without calling real providers.

### 9.5 Documentation site

Docs are built with **MkDocs Material** (`docs/mkdocs.yml`), with the API reference auto-generated by **mkdocstrings** (Google docstring style) from the source of core plus a curated set of integrations. Read the Docs builds it via Poetry. The published site is `https://developers.llamaindex.ai/python/`.

---

## 10. Operations & Deployment Guidance

LlamaIndex has no service to run, so "operations" means how you embed it in your application and manage its external dependencies.

### 10.1 Deployment checklist

- [ ] Pin `llama-index-core` and every integration to compatible versions (respect core's `>=0.14,<0.15` style bounds).
- [ ] Provide all required provider API keys via environment/secret manager.
- [ ] Choose a persistent **vector store** integration (not the in-memory default) for any non-trivial corpus.
- [ ] Match the embedding model at query time to the one used at index time.
- [ ] Attach a **rate limiter** if you batch-index or query at high concurrency.
- [ ] Wire a **global observability handler** and export spans to your APM.
- [ ] Validate and allow-list any user-controlled reader paths/URLs and tool arguments.
- [ ] Decide sync vs async entry points to match your runtime (web handlers/notebooks → async).

### 10.2 Performance tuning

| Lever | Effect |
|-------|--------|
| `similarity_top_k` | More retrieved chunks → better recall, higher token cost/latency |
| `chunk_size` / `chunk_overlap` | Larger chunks → fewer, broader nodes; tune to your content |
| Reranker postprocessor | Improves precision of which chunks reach the LLM |
| Embedding batch size | Higher throughput when indexing large corpora |
| Async + `run_jobs` | Core's `run_jobs(..., workers=N)` runs coroutines with a concurrency semaphore (`DEFAULT_NUM_WORKERS = 4`) for parallel ingestion |
| External vector store | Offloads similarity search from the Python process |

### 10.3 Scaling model

Scale is achieved by delegating to external services: an external vector store for retrieval scale, a hosted/served LLM for generation scale, and an external chat/doc store for stateful, multi-instance deployments. The framework itself is stateless between calls (state lives in `Settings` config and the stores).

---

## 11. Troubleshooting (Operator View)

| Symptom | Root cause | Resolution |
|---------|-----------|------------|
| `Detected nested async...` | Sync method called in a running event loop | Use `aquery`/`aretrieve`/`achat`, or `nest_asyncio.apply()` |
| `ServiceContext is deprecated...` | Legacy config object constructed | Migrate to `Settings`; pass `llm`/`embed_model` directly |
| `ModuleNotFoundError: llama_index.<cat>.<provider>` | Integration package not installed | `pip install llama-index-<cat>-<provider>` |
| `Configured node parser does not have chunk size/overlap.` | Custom parser lacks those attrs but code reads `Settings.chunk_size` | Set sizing on the parser, or use a sentence splitter |
| `At least one of requests_per_minute or tokens_per_minute must be set.` | `SlidingWindowRateLimiter` built with no limits | Provide RPM and/or TPM |
| `embedding not set.` | `.get_embedding()` on an unembedded node | Build via an index; set `Settings.embed_model` |
| Relationship `ValueError`s | Wrong shape for node relationships | Single `RelatedNodeInfo` for SOURCE/PREV/NEXT/PARENT, list for CHILD |
| Provider auth/429 errors | Missing key or quota exceeded | Set env var; add rate limiter; lower concurrency |

Community-reported issues worth tracking for ingestion/serialization edge cases include object-serialization mismatches and `refresh_ref_docs()`/`arefresh_ref_docs()` dropping kwargs after the first document in a batch — relevant if you build incremental re-indexing.

---

## 12. Code Quality & Conventions

- **Pydantic everywhere.** The data model and most components are Pydantic `BaseModel`s, giving validation, schema generation, and stable serialization (`class_name` injection via `BaseComponent`).
- **Sync + async symmetry.** Public methods come in pairs (`query`/`aquery`, `chat`/`achat`, `acquire`/`async_acquire`). `core/async_utils.py` provides `asyncio_run`, `run_jobs`, and `batch_gather` to bridge sync and async safely (including the nested-loop fallback).
- **Abstract base + many concretes.** Every pluggable concern is an ABC in core; behavior comes from subclasses shipped as packages.
- **Backward compatibility via shims and aliases.** Deprecated names are retained (`GPT*Index` aliases, `RateLimiter = TokenBucketRateLimiter`, `SQLContextBuilder`, `Prompt`) and deprecations are explicit (`@deprecated`, loud `ServiceContext` error).
- **Strict typing & linting.** `mypy --disallow-untyped-defs`, `ruff` with a curated rule set, Google-style docstrings enforced for the API-reference generator.

---

## 13. Potential Improvements & Technical Debt

These are observations grounded in the source, offered as a starting point for maintainers and forks:

- **Backward-compat surface is broad.** Many legacy aliases (`GPTVectorStoreIndex` et al.), the `extra_info`/`node_info` deprecations, and the `ServiceContext` shim accumulate. A documented deprecation timeline would help downstream users plan migrations.
- **Per-node pickle-filtering in `BaseComponent.__getstate__`** silently drops unpickleable attributes with a warning ("kind of dangerous", per the source comment). This can cause subtle state loss on serialization; a stricter or opt-in mode would be safer.
- **Reader input trust.** Connectors would benefit from a shared, opt-in path/URL sanitization helper given the breadth of the reader ecosystem and the path-traversal class of issue seen in the wild.
- **Integration uniformity at scale.** With 300+ packages, drift in patterns is inevitable; the `llama-dev` tooling is the right lever, and expanding it (lint rules for integration shape, `cmd-exec` test matrices) would keep the ecosystem consistent.
- **Embedding-model/index coupling is implicit.** Persisted indexes don't record which embedding model produced them; embedding metadata in the stored index would prevent silent mismatch on reload.

---

## 14. Quick Reference (Admin)

### Package map

```
llama-index            → starter bundle (core + openai llm/embeddings + nltk)
llama-index-core       → framework
llama-index-instrumentation → events/spans (also vendored into core)
llama-index-<cat>-<provider> → 300+ integrations
llama-dev              → contributor monorepo CLI (Click)
```

### Contributor CLI

```bash
llama-dev pkg info --all --json
llama-dev pkg bump <package> --version-type patch --dry-run
llama-dev pkg cmd-exec --all --cmd "pytest" --fail-fast
```

### Core defaults

| Constant | Value |
|----------|-------|
| chunk size / overlap | 1024 / 20 tokens |
| similarity top-k | 2 |
| temperature | 0.1 |
| context window | 3900 |
| num output | 256 |
| embed batch size | 10 |
| embedding dim | 1536 |
| async workers (`run_jobs`) | 4 |

### Extension points

| Concern | Base class (core) |
|---------|-------------------|
| LLM | `llms.LLM` / `CustomLLM` |
| Embedding | `base.embeddings.BaseEmbedding` |
| Vector store | `vector_stores.types.BasePydanticVectorStore` |
| Reader | `readers.base.BaseReader` |
| Transform | `schema.TransformComponent` |
| Output parser | `types.BaseOutputParser` |
| Rate limiter | `rate_limiter.BaseRateLimiter` |

### Key facts

| | |
|---|---|
| Python | `>=3.10,<4.0` |
| License | MIT |
| Build | hatchling + uv |
| Lint/type | ruff (py312) + mypy |
| Docs | MkDocs Material + mkdocstrings |
| Security bounty scope | `llama-index`, core, llms-openai, embeddings-openai, cli (via Huntr) |

---

_Generated June 2026 from run-llama/llama_index at 9aa5ee5. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._