docstring for resources.chat.completions.create

Author: mmacy

docs/reference/include/openai.resources.py

@@ -1,5 +1,18 @@
 """Snippets in this docstring are ingested by other documentation (including library docstrings) during the MkDocs build process.
 
+# --8<-- [start:resources]
+The `resources` module aggregates classes and functions for interacting with the OpenAI API into several submodules,
+each representing a specific resource or feature of the API.
+
+The submodules' classes mirror the structure of the API's endpoints and offer synchronous and asynchronous
+communication with the API.
+
+Each resource is accessible as an attribute on the [`OpenAI`][src.openai.OpenAI] and [`AsyncOpenAI`][src.openai.AsyncOpenAI]
+clients. To work with a resource, initialize an instance of one of the clients and access the resource as an attribute
+on the client instance. For example, to work with the `chat` resource, create an instance of the `OpenAI` client and
+access the attributes and methods on `your_client_instance.chat`.
+# --8<-- [end:resources]
+
 # --8<-- [start:audio]
 The `audio` module provides classes for handling various audio processing operations, including transcription of audio to text, translation of spoken content, and speech synthesis.
 
@@ -15,7 +28,7 @@
 # --8<-- [start:chat]
 The `chat` module provides classes for creating and managing chat sessions that leverage OpenAI's language models to generate conversational responses.
 
-The module supports both synchronous and asynchronous operations, offering interfaces for direct interaction with the completion endpoints tailored for chat applications. Designed for developers looking to integrate AI-powered chat functionalities into their applicationsand features like raw and streaming response handling for more flexible integration.
+The module supports both synchronous and asynchronous operations, offering interfaces for direct interaction with the completion endpoints tailored for chat applications. Designed for developers looking to integrate AI-powered chat functionalities into their applications and features like raw and streaming response handling for more flexible integration.
 # --8<-- [end:chat]
 
 # --8<-- [start:chat_completions]

docs/reference/include/openai_init.py

@@ -8,15 +8,34 @@
 provides both synchronous and asynchronous API clients, options to configure their behavior, and modules that provide
 Python code with an API surface to interact with the OpenAI platform.
 
-To get started, check out the documentation for the module representing the [resource][src.openai.resources] you're interested in using for your
-project. For example, the [`resources.chat.completions`][src.openai.resources.chat.completions] module is what you'd use
+To get started, read the submodule descriptions in [`resources`][src.openai.resources] to determine which best fits your
+project. For example, the [`resources.chat`][src.openai.resources.chat] submodule description indicates it's a good fit
 for conversational chat-style interactions with an LLM like [GPT-4 Turbo](https://platform.openai.com/docs/models/gpt-4-and-gpt-4-turbo).
-Or, maybe you need the [`resources.audio`][src.openai.resources.audio] module for performing audio transcription, translation, and
-speech synthesis in your app.
+Or, maybe you need the [`resources.audio`][src.openai.resources.audio] module to perform audio transcription,
+translation, and speech synthesis in your app.
 
-Documentation for the library's main API client classes, [`OpenAI`][src.openai.OpenAI] and
-[`AsyncOpenAI`][src.openai.AsyncOpenAI], is another good place to start. The clients are the primary contact point for
-your code that needs to work with any of the resources available on OpenAI API endpoints.
+Once you've determined the resource to use, create an [`OpenAI`][src.openai.OpenAI] or [`AsyncOpenAI`][src.openai.AsyncOpenAI]
+client instance and access the instance attribute for that resource on the client object. For example, if you instantiate
+an `OpenAI` client object named `client`, youd access the [`OpenAI.chat`][src.openai.OpenAI.chat] instance attribute:
+
+```python
+from openai import OpenAI
+
+# Reads API key from OPENAI_API_KEY environment variable
+client = OpenAI()
+
+# Use the `chat` resource to interact with the OpenAI chat completions endpoint
+completion = client.chat.completions.create(
+    model="gpt-4",
+    messages=[
+        {
+            "role": "user",
+            "content": "Say this is a test",
+        },
+    ],
+)
+print(completion.choices[0].message.content)
+```
 
 For more information about the REST API this package talks to or to find client libraries for other programming
 languages, see:

mkdocs-requirements.txt

@@ -1,13 +1,20 @@
+annotated-types==0.6.0
+anyio==4.3.0
 Babel==2.14.0
 black==24.1.1
 certifi==2024.2.2
 charset-normalizer==3.3.2
 click==8.1.7
 colorama==0.4.6
+distro==1.9.0
 ghp-import==2.1.0
 griffe==0.40.1
 griffe-inherited-docstrings==1.0.0
+h11==0.14.0
+httpcore==1.0.3
+httpx==0.26.0
 idna==3.6
+iniconfig==2.0.0
 Jinja2==3.1.3
 Markdown==3.5.2
 MarkupSafe==2.1.5
@@ -16,22 +23,31 @@ mkdocs==1.5.3
 mkdocs-autorefs==0.5.0
 mkdocs-gen-files==0.5.0
 mkdocs-literate-nav==0.6.1
-mkdocs-material==9.5.8
+mkdocs-material==9.5.9
 mkdocs-material-extensions==1.3.1
 mkdocstrings==0.24.0
 mkdocstrings-python @ git+ssh://[email protected]/pawamoy-insiders/mkdocstrings-python.git@157224dddefd2f2b979f9e92f0506e44c1548f64
 mypy-extensions==1.0.0
+openai==1.12.0
 packaging==23.2
 paginate==0.5.6
 pathspec==0.12.1
 platformdirs==4.2.0
+pluggy==1.4.0
+pydantic==2.6.1
+pydantic_core==2.16.2
 Pygments==2.17.2
 pymdown-extensions==10.7
+pytest==8.0.1
 python-dateutil==2.8.2
 PyYAML==6.0.1
 pyyaml_env_tag==0.1
 regex==2023.12.25
 requests==2.31.0
+respx==0.20.2
 six==1.16.0
+sniffio==1.3.0
+tqdm==4.66.2
+typing_extensions==4.9.0
 urllib3==2.2.0
 watchdog==4.0.0

src/openai/resources/__init__.py

@@ -1,5 +1,5 @@
 # File generated from our OpenAPI spec by Stainless.
-
+""" --8<-- 'docs/reference/include/openai.resources.py:resources' """
 from .beta import (
     Beta,
     AsyncBeta,

src/openai/resources/chat/completions.py

@@ -660,6 +660,83 @@ def create(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> ChatCompletion | Stream[ChatCompletionChunk]:
+        """Creates a model response for the given chat conversation, tailored by a variety of customizable parameters.
+
+        This method allows for detailed control over the chat completion process, including model selection,
+        response formatting, and dynamic interaction through streaming.
+
+        Args:
+            messages (Iterable[ChatCompletionMessageParam]):
+                Messages comprising the conversation so far. Example Python code available at
+                [How to format inputs to ChatGPT models](https://cookbook.openai.com/examples/how_to_format_inputs_to_chatgpt_models).
+            model (str | Literal[...]):
+                ID of the model to use. Refer to the [model endpoint compatibility](https://platform.openai.com/docs/models/model-endpoint-compatibility)
+                table for details on which models are compatible with the Chat API.
+            stream (Literal[True]):
+                If True, enables streaming of message deltas. Tokens are sent as server-sent events as they become available,
+                terminating with a `data: [DONE]` message. See [Using server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format)
+                for more on this format and [How to stream completions](https://cookbook.openai.com/examples/how_to_stream_completions)
+                for example Python code.
+            frequency_penalty (Optional[float], default=NOT_GIVEN):
+                Adjusts token generation frequency to discourage repetition, with a range between -2.0 and 2.0.
+                More details at [frequency and presence penalties](https://platform.openai.com/docs/guides/text-generation/parameter-details).
+            function_call (completion_create_params.FunctionCall, optional):
+                Deprecated in favor of `tool_choice`. Controls the function call behavior within the model.
+            functions (Iterable[completion_create_params.Function], optional):
+                Deprecated in favor of `tools`. Lists functions the model can call.
+            logit_bias (Optional[Dict[str, int]], default=NOT_GIVEN):
+                Modifies the likelihood of specified tokens. Accepts a dict mapping token IDs to bias values (-100 to 100).
+            logprobs (Optional[bool], default=NOT_GIVEN):
+                Includes log probabilities of output tokens when True. Not available for `gpt-4-vision-preview`.
+            max_tokens (Optional[int], default=NOT_GIVEN):
+                Sets the maximum token count for the chat completion. See [How to count tokens with TikToken](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken)
+                for token counting examples.
+            n (Optional[int], default=NOT_GIVEN):
+                Number of chat completion choices to generate for each message. Affects cost.
+            presence_penalty (Optional[float], default=NOT_GIVEN):
+                Adjusts for token presence to promote topic diversity, with a range between -2.0 and 2.0.
+            response_format (completion_create_params.ResponseFormat, optional):
+                Specifies the model output format, compatible with GPT-4 Turbo and GPT-3.5 Turbo models newer than
+                `gpt-3.5-turbo-1106`. JSON mode ensures valid JSON output.
+            seed (Optional[int], default=NOT_GIVEN):
+                Seeds the RNG for deterministic outputs. Beta feature.
+            stop (Union[Optional[str], List[str]], default=NOT_GIVEN):
+                Sequences indicating when to halt token generation.
+            temperature (Optional[float], default=NOT_GIVEN):
+                Controls output randomness. Recommended to adjust this or `top_p`, but not both.
+            tool_choice (ChatCompletionToolChoiceOptionParam, optional):
+                Selects a tool or function for the model to use.
+            tools (Iterable[ChatCompletionToolParam], optional):
+                Specifies available tools for the model, currently limited to functions.
+            top_logprobs (Optional[int], default=NOT_GIVEN):
+                Returns top log probabilities for each token position. Requires `logprobs` to be True.
+            top_p (Optional[float], default=NOT_GIVEN):
+                Nucleus sampling parameter, considering only the top probability mass for generation.
+            user (str | NotGiven):
+                Unique identifier for the end-user, assisting in abuse monitoring. Learn more at
+                [End-user IDs](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids).
+            extra_headers (Headers, optional):
+                Additional HTTP headers for the request.
+            extra_query (Query, optional):
+                Additional query parameters for the request.
+            extra_body (Body, optional):
+                Additional body content for the request.
+            timeout (float | httpx.Timeout | None | NotGiven, default=NOT_GIVEN):
+                Custom timeout for this request, overriding the default settings.
+
+        Returns:
+            Stream[ChatCompletionChunk]: A stream of chat completion chunks for real-time interaction.
+
+        Examples:
+            >>> create(
+            ...     messages=[{"role": "user", "content": "Hello, world!"}],
+            ...     model="gpt-3.5-turbo",
+            ...     stream=True,
+            ...     frequency_penalty=0.5,
+            ...     # Additional parameters...
+            ... )
+            <Stream of ChatCompletionChunk>
+        """
         return self._post(
             "/chat/completions",
             body=maybe_transform(