Core API
Purpose and Scope
The core API is the shared foundation that application code, examples, and integration packages build on when using LlamaIndex. The package README describes llama-index-core as the core Python package for the LlamaIndex library and frames it around foundational building blocks for LLM applications, especially retrieval augmented generation. Those building blocks include abstractions for LLMs, vector stores, embeddings, storage, callables, and related extension points. In practice, this means readers should treat the core package as the stable vocabulary for documents, nodes, component serialization, structured output parsing, and program-like LLM calls, while provider-specific packages supply concrete implementations.
Sources: llama-index-core/README.md, llama-index-core/llama_index/core/types.py, llama-index-core/llama_index/core/schema.py
The public API is intentionally split between core abstractions and integrations. The README says the core library is designed so it can be extended through subclasses, and that building applications involves using LlamaIndex core together with whichever LlamaIndex integrations are needed. That design matters for API readers because a class in core often defines the contract rather than the backing service. For example, an embedding provider, vector database, tool connector, or hosted parser may live outside the core package, but it still participates in the application through core data structures, serialization hooks, callback instrumentation mixins, and common typing conventions.
Sources: llama-index-core/README.md
Relevant Source Files
llama-index-core/README.md- Defines the package-level purpose ofllama-index-core, its relationship to RAG applications, and its extension model with integrations.llama-index-core/llama_index/core/types.py- Provides foundational type aliases and abstract interfaces for output parsers and Pydantic-backed LLM programs.llama-index-core/llama_index/core/schema.py- Defines base schema objects, serialization behavior, media helpers, templates, and the component base used by many higher-level data structures.docs/api_reference/api_reference/schema/index.md- Connects the generated documentation page to thellama_index.core.schemamodule through the API reference directive.
System-to-Code Mapping
At the package level, the core API is the part of the repository that names the reusable concepts used throughout the framework. The README lists LLMs, vector stores, embeddings, storage, and callables as important families, while the official component guide organizes the framework around models, prompts, loading, indexing, and storing. The requested files show two foundational layers underneath those families. The types.py module captures abstract callable behavior for structured LLM output, and the schema.py module captures serializable component and data-model behavior. Together they let higher-level modules exchange values without depending on a particular integration provider.
Sources: llama-index-core/README.md, llama-index-core/llama_index/core/types.py, llama-index-core/llama_index/core/schema.py
The mapping is easiest to understand from the direction of data flow. Loading produces document-like schema objects; parsing and indexing convert them into node-like structures; retrieval and response synthesis pass text, metadata, and model outputs through common classes; agents and workflows can then call tools or programs that return structured results. The source snippets do not expose every class in the schema module, but they do show the base serialization strategy, default text and metadata templates, image input type support, and compatibility imports for external document formats. That makes schema.py the API reference home for cross-cutting data structures rather than a single feature module.
Sources: llama-index-core/llama_index/core/schema.py, docs/api_reference/api_reference/schema/index.md
Core Primitives
BaseComponent is the visible base primitive in the schema source. It extends the project’s Pydantic bridge base model and injects a class_name property into JSON schema generation. The class-level class_name() method returns a serialization identifier, and the model serializer adds that identifier into dumped data. This is important because the source comment explains that the identifier is meant to remain robust even when the actual Python class name changes. For developers writing reusable components, the practical lesson is to provide stable class names and allow the core serialization layer to preserve type identity across persistence, configuration, and interchange boundaries.
Sources: llama-index-core/llama_index/core/schema.py
The schema module also includes compatibility and presentation utilities that shape how core objects are displayed and stored. Constants such as DEFAULT_TEXT_NODE_TMPL, DEFAULT_METADATA_TMPL, TRUNCATE_LENGTH, and WRAP_WIDTH indicate that text content, metadata rendering, truncation, and pretty printing are first-class concerns. The module imports image, base64, JSON, pickle, file type, URL, and path support, which aligns with the broader documentation claim that core components handle more than a single text-only path. Even when users mostly interact with indexes or engines, their objects inherit these lower-level rules for readable output and safe serialization.
Sources: llama-index-core/llama_index/core/schema.py
The types.py module defines the structured-output side of the core API. It introduces generator aliases for streaming text tokens, an async token generator alias, and a response text union that can represent a Pydantic model, a string, or streaming token sources. It also defines BaseOutputParser, an abstract class with a required parsing method and optional formatting behavior. The parser can modify chat messages by applying formatting instructions to either a system message or the final message, depending on the roles present. This gives structured output logic a consistent place in LLM calls without forcing every model integration to invent its own parser contract.
Sources: llama-index-core/llama_index/core/types.py
BasePydanticProgram is the corresponding contract for LLM-powered functions that return Pydantic models. It is generic over a model type, exposes an abstract output_cls property, and requires synchronous callable behavior that returns either one model or a list of models. The async default delegates to the synchronous call, while streaming is explicitly left for implementations that support it. The source labels this interface as not yet stable, so API consumers should prefer documented usage patterns and keep subclass implementations narrow. Still, the shape is clear: a program wraps prompting, model invocation, validation, and structured return values behind a callable Python object.
Sources: llama-index-core/llama_index/core/types.py
Compact Reference
| API surface | Source module | Contract shown in source |
|---|---|---|
TokenGen | llama_index.core.types | Synchronous generator of text token strings. |
TokenAsyncGen | llama_index.core.types | Asynchronous generator of text token strings. |
RESPONSE_TEXT_TYPE | llama_index.core.types | Union covering Pydantic models, strings, and sync or async token streams. |
BaseOutputParser.parse(output: str) -> Any | llama_index.core.types | Required parser hook for validating, correcting, or transforming model output. |
BaseOutputParser.format(query: str) -> str | llama_index.core.types | Optional formatting hook for adding structured output instructions. |
BaseOutputParser.format_messages(messages) | llama_index.core.types | Applies formatting instructions to a system message when present, otherwise to the last message. |
BasePydanticProgram.output_cls | llama_index.core.types | Abstract property naming the returned Pydantic model class. |
BasePydanticProgram.__call__(*args, **kwargs) | llama_index.core.types | Required synchronous invocation returning a model or list of models. |
BasePydanticProgram.acall(*args, **kwargs) | llama_index.core.types | Async convenience path that delegates to synchronous invocation by default. |
BaseComponent.class_name() | llama_index.core.schema | Stable serialization identifier for component classes. |
BaseComponent.json() and BaseComponent.dict() | llama_index.core.schema | Compatibility wrappers around Pydantic dump behavior. |
Implementation Details and Edge Cases
The output parser message-formatting behavior is small but important. The implementation scans a chat message for text blocks, appends formatting instructions to the last text block when one exists, and creates a new text block when none exists. Across a list of messages, it prefers the first message if that message has the system role; otherwise it modifies the final message. This protects common chat prompting patterns: system instructions remain the preferred place for global formatting rules, while single-turn prompts still receive instructions at the point closest to the user query.
Sources: llama-index-core/llama_index/core/types.py
Serialization has a similar set of practical safeguards. BaseComponent overrides JSON schema generation to add class_name, wraps model dumping to include the same identifier, and provides compatibility methods named json and dict. Its pickling support removes attributes that cannot be pickled and logs warnings while doing so. That behavior is intentionally defensive: component objects may contain clients, callbacks, file handles, or other runtime-only members that should not break persistence of the rest of the object. Developers should avoid relying on unpickleable private state surviving a persistence round trip.
Sources: llama-index-core/llama_index/core/schema.py
The generated API reference entry for schema is deliberately terse: it points the documentation system at llama_index.core.schema. That means the authoritative reference page is built from the module and its docstrings rather than hand-maintained markdown. For readers, this page should be used as an orientation layer before opening the generated reference. For maintainers, it means changes to schema classes, fields, validators, serializers, or docstrings can affect the rendered API documentation directly. Keep public names and serialization semantics stable when changing schema objects that are used by persisted indexes or integrations.
Sources: docs/api_reference/api_reference/schema/index.md, llama-index-core/llama_index/core/schema.py
How to Use This Page
Use the core API page when you need to understand what belongs in llama-index-core and what should be provided by an integration package. If you are writing application code, start with the higher-level pages for documents, nodes, indexes, retrievers, query engines, chat engines, or agents, then return here when you need to reason about shared base classes or typed contracts. If you are implementing an extension, inspect the core abstract classes first, then implement only the provider-specific behavior in the integration. That keeps your code aligned with the package split described by the README.
Sources: llama-index-core/README.md, llama-index-core/llama_index/core/types.py, llama-index-core/llama_index/core/schema.py
For adjacent reading, move from this page to the schema-focused document and node guide when you are shaping data, to the models and settings guide when you are selecting LLM or embedding providers, and to the storage or vector-store pages when persistence is the main concern. Agent and workflow users should also understand tools, callbacks, instrumentation, and MCP-related integration pages, because those capabilities connect external resources and structured calls to the same core data and typing layer. The key rule is simple: core defines the reusable contract, while integrations and application modules provide the concrete runtime behavior.