Implementation:Run llama Llama index Command Line Mappings
| Knowledge Sources | |
|---|---|
| Domains | Migration, CLI Tooling, Import Management |
| Last Updated | 2026-02-11 19:00 GMT |
Overview
A JSON lookup table mapping class and symbol names from the old monolithic LlamaIndex package to their new modular import paths for the automated migration tool.
Description
llama-index-core/llama_index/core/command_line/mappings.json is a 1,095-line JSON file structured as a flat object where keys are class or symbol names and values are their new fully qualified module paths. This data file powers the automated migration/upgrade tool (upgrade.py), enabling users to automatically rewrite their import statements when upgrading from the monolithic LlamaIndex v0.9.x to the modular v0.10.x+ architecture.
The file covers hundreds of symbols across every major domain of LlamaIndex:
- Core types:
StorageContext,Settings,Document,QueryBundle - Indices:
VectorStoreIndex,TreeIndex,DocumentSummaryIndex,KnowledgeGraphIndex,PropertyGraphIndex - Prompts:
PromptTemplate,ChatPromptTemplate,SelectorPromptTemplate - Agents:
AgentRunner,ReActAgent,FunctionCallingAgentWorker - Callbacks:
CallbackManager,LlamaDebugHandler,TokenCountingHandler - Chat engines:
SimpleChatEngine,CondenseQuestionChatEngine,ContextChatEngine - Embeddings:
BaseEmbedding,MultiModalEmbedding,resolve_embed_model - Evaluation:
BaseEvaluator,FaithfulnessEvaluator,BatchEvalRunner - Extractors:
SummaryExtractor,TitleExtractor,KeywordExtractor - Graph stores:
SimpleGraphStore,SimplePropertyGraphStore,EntityNode - Legacy aliases:
GPTVectorStoreIndex,GPTTreeIndex,ListIndex
The file also includes commented entries (prefixed with #) that serve as section headers or notes, such as "# indicesSummaryIndex" and "# legacy: kept for backward compatibilityQueryResponseEvaluator".
Usage
This file is consumed by the LlamaIndex CLI migration tool. When users run the upgrade command, the tool reads this mapping to identify old import paths in user code and replace them with the correct new module paths. Developers extending LlamaIndex with new public classes should add entries here to ensure the migration tool handles them correctly.
Code Reference
Source Location
- Repository: Run_llama_Llama_index
- File:
llama-index-core/llama_index/core/command_line/mappings.json - Lines: 1-1095
Format
{
"StorageContext": "llama_index.core",
"VectorStoreIndex": "llama_index.core",
"PromptTemplate": "llama_index.core",
"Settings": "llama_index.core",
"AgentRunner": "llama_index.core.agent",
"ReActAgent": "llama_index.core.agent",
"CallbackManager": "llama_index.core.callbacks",
"BaseEmbedding": "llama_index.core.embeddings",
"SimplePropertyGraphStore": "llama_index.core.graph_stores"
}
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| JSON file | File | Yes | Read by the upgrade/migration CLI tool at runtime |
Outputs
| Name | Type | Description |
|---|---|---|
| Symbol-to-module mapping | Dict[str, str] | Maps each class/function name to its new module path |
Mapping Categories
Module Path Distribution
| Target Module | Example Symbols | Description |
|---|---|---|
llama_index.core |
StorageContext, VectorStoreIndex, Document, Settings | Top-level core imports |
llama_index.core.agent |
AgentRunner, ReActAgent, FunctionCallingAgentWorker | Agent framework classes |
llama_index.core.callbacks |
CallbackManager, LlamaDebugHandler, TokenCountingHandler | Callback and instrumentation |
llama_index.core.chat_engine |
SimpleChatEngine, ContextChatEngine | Chat engine implementations |
llama_index.core.evaluation |
FaithfulnessEvaluator, BatchEvalRunner, HitRate | Evaluation framework |
llama_index.core.extractors |
SummaryExtractor, TitleExtractor, KeywordExtractor | Metadata extraction |
llama_index.core.graph_stores |
SimpleGraphStore, SimplePropertyGraphStore, EntityNode | Graph store types |
llama_index.core.embeddings |
BaseEmbedding, MultiModalEmbedding | Embedding abstractions |
Usage Examples
Using the Migration Tool
# Run the LlamaIndex upgrade CLI to migrate import paths
llamaindex-cli upgrade --input my_project/
Programmatic Access
import json
from pathlib import Path
mappings_path = Path("llama-index-core/llama_index/core/command_line/mappings.json")
with open(mappings_path) as f:
mappings = json.load(f)
# Look up the new module for a symbol
new_module = mappings.get("VectorStoreIndex")
# Returns: "llama_index.core"