openai / openai/openai-python

Update index documentation

Open
#2,512 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

openapi
Dominant language
Python
Stars
31.6k
Forks
5.7k
Avg merge
1d 6h
Merged PRs (30d)
96

Description

AnnotationFileCitation wrongly references a file index instead of a text index. To match the url citation better, I suggest """The index at which to insert the file citation in the message.""". A more verbose string could give an example of inserting the citation.

https://github.com/openai/openai-python/blob/a8258744cbecf51321587fc870e8920bd2c07809/src/openai/types/responses/response_output_text.py#L28-L29

My interpretation is founded in a discussion and experimental observation that index lines up with the end of a word in the output_text. Note that for a "manual" check account for new lines as a single character and be aware that a text editor may not have a zero-indexed character position.

See also the file search guide. It is slightly ambiguous until tested that it refers to to an insertion point and not the location within the cited document.

Making a further observation within the same file, AnnotationFilePath has the same documentation for index, but it isn't relevant to my use case so I'm not sure how accurate it is.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at src/openai/types/responses/response_output_text.py around lines 28-29 and compare the index documentation for AnnotationFileCitation with the URL citation. Update the wording to describe the citation insertion point, then check whether the parallel AnnotationFilePath text also needs clarification; done means the affected documentation accurately describes index behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.