[BenA-SA]

Description

Removes the openai<3 upper bound from llama-index-llms-openai, allowing openai>=1.108.1.

Why I am raising this. I want to use a 3.x release of the openai SDK in one of my projects, and I currently cannot: this package pins openai<3, and because it is pulled in transitively (in my case via OpenAILike), the resolver refuses the newer SDK for the whole environment. Rather than just ask for the bump, I did the testing to check the package actually handles it, and this PR is the result.

The cap looks precautionary rather than reactive. It was introduced in 0.7.0 on 2026-03-12, and openai 3.0.0 shipped on 2026-08-12, five months later. So it was a routine next-major bound in the same style as the llama-index-core<0.15 pin, not a response to a known incompatibility. I could not find an existing issue or PR proposing 3.x support.

What I checked

Against openai==3.7.0, with openai==2.54.0 as the baseline for comparison:

• The full package suite passes on both majors, including the API-backed tests that are normally skipped when OPENAI_API_KEY is unset. Those cover chat, completion, sync and async streaming, structured prediction, built-in tools and document upload, so the real serialisation path is exercised, not only mocks.
• Every openai import path the package uses still resolves, including all of the openai.types.responses and openai.types.chat symbols in base.py and responses.py, and the four exception types utils.py retries on. Nothing the package references was removed or moved.
• No parameter was removed from any client method the package calls (chat.completions.create, completions.create, responses.create, responses.parse) or from the client constructors.
• HTTPX2, the one documented breaking change in 3.0.0, is not a problem here. The package never constructs a transport itself, it only forwards an optional http_client / async_http_client. openai 3 accepts both an httpx and an httpx2 client, and requests succeed through either, including streaming.

The one test change

ResponseOutputTextAnnotationAddedEvent.annotation was typed as a bare object in openai 2 and is a discriminated union of annotation models in openai 3. test_process_response_event_with_text_annotation built a placeholder {"type": "test_annotation", "value": 42} payload, which only validated because the field previously accepted anything.

The test now uses a real url_citation annotation and normalises the stored value, since openai 2 leaves it as a dict while openai 3 parses it into a model. It passes on both majors. The library code needed no change: process_response_event appends the annotation without inspecting it.

One thing worth flagging separately

base.py and responses.py both import httpx at module scope, but the package does not declare httpx as a dependency. Under openai 2 this was masked because openai installed httpx itself. openai 3 depends on httpx2 instead, so after this change the import survives only because llama-index-core happens to declare httpx.

I have deliberately not bundled a fix here, because the right answer may be to accept both client families rather than to adopt a dependency the SDK is moving away from, and that is a maintainer call. Happy to open a separate issue or PR for it, whichever you prefer.

Fixes # (no issue)

New Package?

• Yes
• No

Version Bump?

• Yes (0.8.3 to 0.9.0, minor since the dependency range widens)
• No

Type of Change

• Bug fix (non-breaking change which fixes an issue): removes an upper bound that blocks downstream resolution

How Has This Been Tested?

• I believe this change is already covered by existing unit tests

The existing suite was run in full against both openai==2.54.0 and openai==3.7.0.

Note that CI does not set OPENAI_API_KEY, so the API-backed tests are skipped there. I ran them locally with my own key, on both majors, which is what gives me confidence the change is safe beyond the mocked paths. I have opened #22938 separately to add coverage for some untested areas, including http_client, which is the surface this change touches most directly. That PR is independent of this one and passes on the current pinned range, but it would make this change better covered if merged first.

Suggested Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• New and existing unit tests pass locally with my changes
• I ran the linters (ruff check and ruff format --check both clean for the touched files)

AI assistance disclosure

Per the "How to Use AI when Contributing" section of CONTRIBUTING.md: this change was investigated with AI assistance. The conclusions are backed by actual test runs against both openai majors rather than by model inspection alone, including the live API-backed tests, and the SDK comparison was done by diffing the installed packages and reading the upstream diff between the two versions.

[grabear]

+1 here. This is limiting for me as well.

[BenA-SA]

Hi, a gentle nudge on this one when someone has a moment.

Since it was opened, apache/airflow#73511 (merged 22 Sep) has had to hold openai on 2.x in its lockfile and CI image because of this package's openai<3 cap, and it names this PR as the upstream change it is waiting on to drop that override. Its description also reports llama-index chat and embeddings working on openai 3.16, which matches what I found here: the package suite passes on both openai 2.54 and 3.17 as of the latest rebase.

The CI workflows are still waiting for approval, since this is my first contribution to the repo, so only the new-pyproject check has run. If a maintainer could approve the runs, I'm happy to fix anything they turn up, and to rebase or re-bump the version if main moves again.

The companion test-coverage PR, #22938, is in the same state.

[upchunk]

Needed this for sure on my project!

[ondraz]

@logan-markewich could you take a look when you have a moment? openai<3 here is now the only thing holding downstream projects on openai 2.x. pydantic-ai-slim ≥2.52, which carries two HIGH security fixes (GHSA-6fqq-452j-qhrp), requires openai>=3.19, so anyone using both packages can't take that fix. We've confirmed in our lock that lifting this cap is the only conflict. Thank you.