Registry /
llm-agents / llama-index-program-openai
Install & Compatibility
Where this runs
tested against v0.3.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 5.818s · 246.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 20.1s · import 5.558s · 242MB
257MB installed
● package 257MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAIPydanticProgram
✓ from llama_index.program.openai import OpenAIPydanticProgram
✗ from llama_index.program import OpenAIPydanticProgram
The modular structure of LlamaIndex requires importing from the specific integration package's namespace.
BaseModel
✓ from pydantic import BaseModel
List
✓ from typing import List
This quickstart demonstrates how to use `OpenAIPydanticProgram` to extract structured data. It defines a Pydantic `Album` schema, constructs a prompt using a template, and then executes the program with an OpenAI LLM to populate the `Album` object based on the given inspiration. Ensure your `OPENAI_API_KEY` environment variable is set.
import os
from pydantic import BaseModel
from typing import List
from llama_index.program.openai import OpenAIPydanticProgram
# Set your OpenAI API key (replace 'sk-...' or ensure it's in your environment)
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-YOUR_OPENAI_KEY_HERE")
# Define your desired structured output schema using Pydantic
class Song(BaseModel):
title: str
length_seconds: int
class Album(BaseModel):
name: str
artist: str
songs: List[Song]
# Define the prompt template for the LLM
prompt_template_str = """
Generate an example album, with an artist and a list of songs.
Using the movie {movie_name} as inspiration.
"""
# Initialize the OpenAI Pydantic program
program = OpenAIPydanticProgram.from_defaults(
output_cls=Album,
prompt_template_str=prompt_template_str,
verbose=True
)
# Run the program to get structured output
output = program(movie_name="The Shining")
# Print the structured output
print(output.json(indent=2))
Debug
Known issues
breakingBeginning with LlamaIndex v0.10, the library adopted a modular package structure. `llama-index-program-openai` is now a standalone package, and core components are in `llama-index-core`. Ensure you install specific integration packages (e.g., `llama-index-llms-openai`) and adjust imports if migrating from older versions where all modules were consolidated under `llama_index`. The `ServiceContext` object was deprecated in v0.10 and fully removed in v0.11; use the `Settings` object or direct parameter passing instead.fixExplicitly install integration packages (`pip install llama-index-llms-openai`) and import from their specific namespaces (e.g., `from llama_index.llms.openai import OpenAI`). Replace `ServiceContext` usage with `Settings` or direct `llm`/`embed_model` parameters.
affects: llama-index >= 0.10.0
breakingLlamaIndex v0.11 fully migrated to Pydantic V2. If your project previously used `pydantic.v1` imports to work around compatibility issues, these should now be removed or updated to Pydantic V2 syntax.fixRemove or update any `pydantic.v1` imports and ensure your Pydantic models are compatible with Pydantic V2.
affects: llama-index >= 0.11.0
gotchaAn `OPENAI_API_KEY` environment variable must be set for `llama-index-program-openai` to function, as it relies on OpenAI's API. Failure to set this will result in an `openai.error.AuthenticationError`.fixSet `os.environ['OPENAI_API_KEY'] = 'your_key_here'` or export it in your shell (`export OPENAI_API_KEY='your_key_here'`) before running your application.
affects: All versions
gotchaWhen using `OpenAIPydanticProgram` within agents that leverage OpenAI's function calling, tool descriptions have a maximum length of 1024 characters. Exceeding this limit will cause an error during tool construction.fixShorten tool descriptions or move extensive details into the LLM prompt instead of the tool's metadata to avoid the character limit.
affects: All versions utilizing OpenAI function calling with tools
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'llama_index.llms.huggingface'
The 'llama_index' library has modularized its components, requiring separate installations for specific modules.
fixInstall the necessary module using pip: 'pip install llama-index-llms-huggingface'.
ModuleNotFoundError: No module named 'llama_index.indices.multi_modal'
The 'llama_index' library has restructured its modules, leading to changes in import paths.
fixUpdate your imports to the new structure: 'from llama_index.core.indices import MultiModalVectorStoreIndex'.
ModuleNotFoundError: No module named 'openai.openai_object'
The 'openai' library has undergone updates that may have removed or relocated certain modules.
fixEnsure you are using a compatible version of the 'openai' library and check the latest documentation for correct import paths.
ModuleNotFoundError: No module named 'llama_index.graph_stores'
The 'llama_index' library has modularized its components, requiring separate installations for specific modules.
fixInstall the necessary module using pip: 'pip install llama-index-graph-stores-nebula'.
ModuleNotFoundError: No module named 'llama_index.embeddings.langchain'
The 'llama_index' library has modularized its components, requiring separate installations for specific modules.
fixInstall the necessary module using pip: 'pip install llama-index-embeddings-langchain'.
Upgrade
Version history
0.3.2latest on PyPI · released May 30, 2025
Audit
Dependencies
llama-index-corerequiredProvides core LlamaIndex abstractions, essential for any LlamaIndex integration.
llama-index-llms-openairequiredRequired for interfacing with OpenAI's Large Language Models (LLMs) which power the Pydantic program.
pydanticrequiredUsed to define the structured output schemas (BaseModel classes) that the program will populate.
openairequiredThe underlying Python client for interacting with the OpenAI API.