ResponseOutputTextAnnotationAddedEvent.annotation typed as object instead of Annotation

[Tesla2000]

Confirm this is an issue with the Python library and not an underlying OpenAI API

• This is an issue with the Python library

Describe the bug

The annotation field on ResponseOutputTextAnnotationAddedEvent is typed as object:

class ResponseOutputTextAnnotationAddedEvent(BaseModel):
    annotation: object
    """The annotation object being added. (See annotation schema for details.)"""

However, response_output_text.py already defines the correct union type:

Annotation: TypeAlias = Annotated[
    Union[AnnotationFileCitation, AnnotationURLCitation, AnnotationContainerFileCitation, AnnotationFilePath],
    PropertyInfo(discriminator="type"),
]

This forces consumers to either suppress type errors or use typing.cast to access typed fields:

# workaround required because annotation is typed as object
annotation = typing.cast(AnnotationURLCitation, stream_event.annotation)
title = annotation.title
url = annotation.url

The fix is to use the existing Annotation type alias:

class ResponseOutputTextAnnotationAddedEvent(BaseModel):
    annotation: Annotation

This is consistent with how ResponseOutputText.annotations: List[Annotation] is already typed in the same file, and would allow consumers to match on annotation.type and access fields without casts.

To Reproduce

from openai.types.responses import ResponseOutputTextAnnotationAddedEvent
from openai.types.responses.response_output_text import AnnotationURLCitation

event = ResponseOutputTextAnnotationAddedEvent(
    annotation={"type": "url_citation", "title": "Example", "url": "https://example.com", "start_index": 0, "end_index": 10},
    annotation_index=0,
    content_index=0,
    item_id="item_123",
    output_index=0,
    sequence_number=1,
    type="response.output_text.annotation.added",
)

# annotation is typed as `object` — none of these work without a cast
reveal_type(event.annotation)  # Revealed type: object
print(event.annotation.url)    # error: Cannot access attribute "url" for class "object"

Running basedpyright on the above produces:

error: Cannot access attribute "url" for class "object"
  Attribute "url" is unknown (reportAttributeAccessIssue)

The consumer is forced to cast:

annotation = typing.cast(AnnotationURLCitation, event.annotation)
print(annotation.url)  # works, but defeats the purpose of static typing

Code snippets

OS

Debian GNU/Linux 12 (bookworm)

Python version

Python v3.14.6

Library version

openai==2.38.0

[nomiveritas]

The issue is not in the OpenAI API itself, but in the Python SDK's type definitions. In the "ResponseOutputTextAnnotationAddedEvent" class, the "annotation" field is currently declared as type "object", even though the codebase already defines the appropriate "Annotation" union type, which includes all supported annotation variants ("AnnotationURLCitation", "AnnotationFileCitation", etc.).

Because of this, static type checkers such as Pyright, BasedPyright, and MyPy cannot correctly infer the annotation type or access its fields. As a result, developers are forced to use "typing.cast()", which partially defeats the purpose of static typing.

The proposed fix is straightforward.

Current definition:

class ResponseOutputTextAnnotationAddedEvent(BaseModel): annotation: object

Proposed definition:

class ResponseOutputTextAnnotationAddedEvent(BaseModel): annotation: Annotation

This change should not affect runtime behavior and should not introduce compatibility issues, as it only strengthens the existing type information already represented by the "Annotation" union. It restores accurate type information, allowing developers to safely access annotation fields and use type narrowing based on "annotation.type" without requiring explicit casts.

This would also make the event model consistent with other parts of the SDK that already use the "Annotation" type.

Respectfully

[nightcityblade]

Hi, I'd like to work on this. I'll submit a PR shortly.

[nightcityblade]

I found that there is already an open PR addressing this issue (#3422), so I'm stepping back to avoid duplicate work. Thanks!

[nomiveritas]

@nightcityblade Please ensure to thoroughly review the list of existing Pull Requests and active branches across repositories before commenting on issues or initiating work.

There is a consistent, platform-wide pattern—highly visible in recent threads here (including but not limited to issues #3419, #3338, #3114, and #2668) as well as across other major open-source organization ecosystems—where repetitive placeholder comments such as "I'll submit a PR shortly" are systematically posted. This often occurs even after complete solutions have already been provided or are actively being developed by other contributors, leading to subsequent closures due to redundancy.

This repetitive, widespread overhead negatively impacts the developer environment in the following ways:

Contributor and Maintainer Fatigue:** Reviewers and active community members must dedicate unnecessary time to manually filtering, auditing, and organizing redundant branches and placeholder threads.
Infrastructure Strain:** Triggering automated CI/CD test pipelines for overlapping or duplicate code strains testing infrastructure and log retention unnecessarily.

Per GitHub’s official Acceptable Use Policy regarding repository activity and community interaction, contributions must minimize noise and maintain the efficiency of open-source workflows. Engaging in a continuous stream of placeholder claims across multiple organizations constitutes disruptive behavior. Please closely coordinate with ongoing PRs prior to claiming tasks to ensure a constructive environment for the entire communit

Respectfully Nomiveritas