From 7ed521112347cc88441f5c5060a8a0bd71e6a96f Mon Sep 17 00:00:00 2001 From: Navadeep0007 <2400030007@kluniversity.in> Date: Thu, 13 Nov 2025 15:05:49 +0530 Subject: [PATCH] docs: clarify meaning of 'index' field in annotation models (fixes #2512) Signed-off-by: Navadeep0007 <2400030007@kluniversity.in> --- .../types/responses/response_output_text.py | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/src/openai/types/responses/response_output_text.py b/src/openai/types/responses/response_output_text.py index aa97b629f0..f9c68899a7 100644 --- a/src/openai/types/responses/response_output_text.py +++ b/src/openai/types/responses/response_output_text.py @@ -26,7 +26,12 @@ class AnnotationFileCitation(BaseModel): """The filename of the file cited.""" index: int - """The index of the file in the list of files.""" + """The position index in the message text where the file citation appears. + + This indicates the location (by character index) in the model’s output text + where the cited file is referenced. For example, if `index=25`, the citation + starts near the 25th character in the output message. + """ type: Literal["file_citation"] """The type of the file citation. Always `file_citation`.""" @@ -74,14 +79,24 @@ class AnnotationFilePath(BaseModel): """The ID of the file.""" index: int - """The index of the file in the list of files.""" + """The position index in the message text where the file path reference appears. + + This indicates where in the text the path citation begins. + For example, if `index=42`, the file path is referenced around the 42nd + character of the model output. + """ type: Literal["file_path"] """The type of the file path. Always `file_path`.""" Annotation: TypeAlias = Annotated[ - Union[AnnotationFileCitation, AnnotationURLCitation, AnnotationContainerFileCitation, AnnotationFilePath], + Union[ + AnnotationFileCitation, + AnnotationURLCitation, + AnnotationContainerFileCitation, + AnnotationFilePath, + ], PropertyInfo(discriminator="type"), ] @@ -115,3 +130,4 @@ class ResponseOutputText(BaseModel): """The type of the output text. Always `output_text`.""" logprobs: Optional[List[Logprob]] = None +