release: 1.102.0

.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
     permissions:
       contents: read
       id-token: write
-    runs-on: depot-ubuntu-24.04
+    runs-on: ${{ github.repository == 'stainless-sdks/openai-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@v4
 

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.101.0"
+  ".": "1.102.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 119
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-ddbdf9343316047e8a773c54fb24e4a8d225955e202a1888fde6f9c8898ebf98.yml
-openapi_spec_hash: 9802f6dd381558466c897f6e387e06ca
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-8517ffa1004e31ca2523d617629e64be6fe4f13403ddfd9db5b3be002656cbde.yml
+openapi_spec_hash: b64dd8c8b23082a7aa2a3e5c5fffd8bd
 config_hash: fe0ea26680ac2075a6cd66416aefe7db

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.102.0 (2025-08-26)
+
+Full Changelog: [v1.101.0...v1.102.0](https://github.com/openai/openai-python/compare/v1.101.0...v1.102.0)
+
+### Features
+
+* **api:** add web search filters ([1c199a8](https://github.com/openai/openai-python/commit/1c199a8dc85f773ae656fe850fdfb80b91f8f6b1))
+
+
+### Bug Fixes
+
+* avoid newer type syntax ([bd0c668](https://github.com/openai/openai-python/commit/bd0c668d754b89c78c2c9ad2e081258c04aaece6))
+
+
+### Chores
+
+* **internal:** change ci workflow machines ([3e129d5](https://github.com/openai/openai-python/commit/3e129d5e49f6391dea7497132cb3cfed8e5dd8ee))
+* **internal:** codegen related update ([b6dc170](https://github.com/openai/openai-python/commit/b6dc170832d719fc5028cfe234748c22e6e168aa))
+
 ## 1.101.0 (2025-08-21)
 
 Full Changelog: [v1.100.3...v1.101.0](https://github.com/openai/openai-python/compare/v1.100.3...v1.101.0)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai"
-version = "1.101.0"
+version = "1.102.0"
 description = "The official Python library for the openai API"
 dynamic = ["readme"]
 license = "Apache-2.0"

requirements-dev.lock

@@ -70,7 +70,7 @@ filelock==3.12.4
 frozenlist==1.7.0
     # via aiohttp
     # via aiosignal
-griffe==1.12.1
+griffe==1.13.0
 h11==0.16.0
     # via httpcore
 httpcore==1.0.9

src/openai/_models.py

@@ -329,7 +329,7 @@ def model_dump(
                 exclude_none=exclude_none,
             )
 
-            return cast(dict[str, Any], json_safe(dumped)) if mode == "json" else dumped
+            return cast("dict[str, Any]", json_safe(dumped)) if mode == "json" else dumped
 
         @override
         def model_dump_json(

src/openai/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "openai"
-__version__ = "1.101.0"  # x-release-please-version
+__version__ = "1.102.0"  # x-release-please-version

src/openai/resources/conversations/conversations.py

@@ -67,7 +67,7 @@ def create(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> Conversation:
         """
-        Create a conversation with the given ID.
+        Create a conversation.
 
         Args:
           items: Initial items to include in the conversation context. You may add up to 20 items
@@ -244,7 +244,7 @@ async def create(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> Conversation:
         """
-        Create a conversation with the given ID.
+        Create a conversation.
 
         Args:
           items: Initial items to include in the conversation context. You may add up to 20 items

src/openai/resources/conversations/items.py

@@ -163,6 +163,8 @@ def list(
           include: Specify additional output data to include in the model response. Currently
               supported values are:
 
+              - `web_search_call.action.sources`: Include the sources of the web search tool
+                call.
               - `code_interpreter_call.outputs`: Includes the outputs of python code execution
                 in code interpreter tool call items.
               - `computer_call_output.output.image_url`: Include image urls from the computer
@@ -391,6 +393,8 @@ def list(
           include: Specify additional output data to include in the model response. Currently
               supported values are:
 
+              - `web_search_call.action.sources`: Include the sources of the web search tool
+                call.
               - `code_interpreter_call.outputs`: Includes the outputs of python code execution
                 in code interpreter tool call items.
               - `computer_call_output.output.image_url`: Include image urls from the computer

src/openai/resources/responses/responses.py

@@ -136,6 +136,8 @@ def create(
           include: Specify additional output data to include in the model response. Currently
               supported values are:
 
+              - `web_search_call.action.sources`: Include the sources of the web search tool
+                call.
               - `code_interpreter_call.outputs`: Includes the outputs of python code execution
                 in code interpreter tool call items.
               - `computer_call_output.output.image_url`: Include image urls from the computer
@@ -377,6 +379,8 @@ def create(
           include: Specify additional output data to include in the model response. Currently
               supported values are:
 
+              - `web_search_call.action.sources`: Include the sources of the web search tool
+                call.
               - `code_interpreter_call.outputs`: Includes the outputs of python code execution
                 in code interpreter tool call items.
               - `computer_call_output.output.image_url`: Include image urls from the computer
@@ -611,6 +615,8 @@ def create(
           include: Specify additional output data to include in the model response. Currently
               supported values are:
 
+              - `web_search_call.action.sources`: Include the sources of the web search tool
+                call.
               - `code_interpreter_call.outputs`: Includes the outputs of python code execution
                 in code interpreter tool call items.
               - `computer_call_output.output.image_url`: Include image urls from the computer
@@ -1524,6 +1530,8 @@ async def create(
           include: Specify additional output data to include in the model response. Currently
               supported values are:
 
+              - `web_search_call.action.sources`: Include the sources of the web search tool
+                call.
               - `code_interpreter_call.outputs`: Includes the outputs of python code execution
                 in code interpreter tool call items.
               - `computer_call_output.output.image_url`: Include image urls from the computer
@@ -1765,6 +1773,8 @@ async def create(
           include: Specify additional output data to include in the model response. Currently
               supported values are:
 
+              - `web_search_call.action.sources`: Include the sources of the web search tool
+                call.
               - `code_interpreter_call.outputs`: Includes the outputs of python code execution
                 in code interpreter tool call items.
               - `computer_call_output.output.image_url`: Include image urls from the computer
@@ -1999,6 +2009,8 @@ async def create(
           include: Specify additional output data to include in the model response. Currently
               supported values are:
 
+              - `web_search_call.action.sources`: Include the sources of the web search tool
+                call.
               - `code_interpreter_call.outputs`: Includes the outputs of python code execution
                 in code interpreter tool call items.
               - `computer_call_output.output.image_url`: Include image urls from the computer

src/openai/types/conversations/item_list_params.py

@@ -19,6 +19,8 @@ class ItemListParams(TypedDict, total=False):
 
     Currently supported values are:
 
+    - `web_search_call.action.sources`: Include the sources of the web search tool
+      call.
     - `code_interpreter_call.outputs`: Includes the outputs of python code execution
       in code interpreter tool call items.
     - `computer_call_output.output.image_url`: Include image urls from the computer

src/openai/types/responses/response_create_params.py

@@ -51,6 +51,8 @@ class ResponseCreateParamsBase(TypedDict, total=False):
 
     Currently supported values are:
 
+    - `web_search_call.action.sources`: Include the sources of the web search tool
+      call.
     - `code_interpreter_call.outputs`: Includes the outputs of python code execution
       in code interpreter tool call items.
     - `computer_call_output.output.image_url`: Include image urls from the computer

src/openai/types/responses/response_function_web_search.py

@@ -1,12 +1,20 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Union
+from typing import List, Union, Optional
 from typing_extensions import Literal, Annotated, TypeAlias
 
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
 
-__all__ = ["ResponseFunctionWebSearch", "Action", "ActionSearch", "ActionOpenPage", "ActionFind"]
+__all__ = ["ResponseFunctionWebSearch", "Action", "ActionSearch", "ActionSearchSource", "ActionOpenPage", "ActionFind"]
+
+
+class ActionSearchSource(BaseModel):
+    type: Literal["url"]
+    """The type of source. Always `url`."""
+
+    url: str
+    """The URL of the source."""
 
 
 class ActionSearch(BaseModel):
@@ -16,6 +24,9 @@ class ActionSearch(BaseModel):
     type: Literal["search"]
     """The action type."""
 
+    sources: Optional[List[ActionSearchSource]] = None
+    """The sources used in the search."""
+
 
 class ActionOpenPage(BaseModel):
     type: Literal["open_page"]

src/openai/types/responses/response_function_web_search_param.py

@@ -2,10 +2,25 @@
 
 from __future__ import annotations
 
-from typing import Union
+from typing import Union, Iterable
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
-__all__ = ["ResponseFunctionWebSearchParam", "Action", "ActionSearch", "ActionOpenPage", "ActionFind"]
+__all__ = [
+    "ResponseFunctionWebSearchParam",
+    "Action",
+    "ActionSearch",
+    "ActionSearchSource",
+    "ActionOpenPage",
+    "ActionFind",
+]
+
+
+class ActionSearchSource(TypedDict, total=False):
+    type: Required[Literal["url"]]
+    """The type of source. Always `url`."""
+
+    url: Required[str]
+    """The URL of the source."""
 
 
 class ActionSearch(TypedDict, total=False):
@@ -15,6 +30,9 @@ class ActionSearch(TypedDict, total=False):
     type: Required[Literal["search"]]
     """The action type."""
 
+    sources: Iterable[ActionSearchSource]
+    """The sources used in the search."""
+
 
 class ActionOpenPage(TypedDict, total=False):
     type: Required[Literal["open_page"]]

src/openai/types/responses/tool.py

@@ -3,16 +3,19 @@
 from typing import Dict, List, Union, Optional
 from typing_extensions import Literal, Annotated, TypeAlias
 
+from . import web_search_tool
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
 from .custom_tool import CustomTool
 from .computer_tool import ComputerTool
 from .function_tool import FunctionTool
-from .web_search_tool import WebSearchTool
 from .file_search_tool import FileSearchTool
 
 __all__ = [
     "Tool",
+    "WebSearchTool",
+    "WebSearchToolFilters",
+    "WebSearchToolUserLocation",
     "Mcp",
     "McpAllowedTools",
     "McpAllowedToolsMcpToolFilter",
@@ -29,6 +32,61 @@
 ]
 
 
+class WebSearchToolFilters(BaseModel):
+    allowed_domains: Optional[List[str]] = None
+    """Allowed domains for the search.
+
+    If not provided, all domains are allowed. Subdomains of the provided domains are
+    allowed as well.
+
+    Example: `["pubmed.ncbi.nlm.nih.gov"]`
+    """
+
+
+class WebSearchToolUserLocation(BaseModel):
+    city: Optional[str] = None
+    """Free text input for the city of the user, e.g. `San Francisco`."""
+
+    country: Optional[str] = None
+    """
+    The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
+    the user, e.g. `US`.
+    """
+
+    region: Optional[str] = None
+    """Free text input for the region of the user, e.g. `California`."""
+
+    timezone: Optional[str] = None
+    """
+    The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
+    user, e.g. `America/Los_Angeles`.
+    """
+
+    type: Optional[Literal["approximate"]] = None
+    """The type of ___location approximation. Always `approximate`."""
+
+
+class WebSearchTool(BaseModel):
+    type: Literal["web_search", "web_search_2025_08_26"]
+    """The type of the web search tool.
+
+    One of `web_search` or `web_search_2025_08_26`.
+    """
+
+    filters: Optional[WebSearchToolFilters] = None
+    """Filters for the search."""
+
+    search_context_size: Optional[Literal["low", "medium", "high"]] = None
+    """High level guidance for the amount of context window space to use for the
+    search.
+
+    One of `low`, `medium`, or `high`. `medium` is the default.
+    """
+
+    user_location: Optional[WebSearchToolUserLocation] = None
+    """The approximate ___location of the user."""
+
+
 class McpAllowedToolsMcpToolFilter(BaseModel):
     read_only: Optional[bool] = None
     """Indicates whether or not a tool modifies data or is read-only.
@@ -245,13 +303,14 @@ class LocalShell(BaseModel):
     Union[
         FunctionTool,
         FileSearchTool,
-        WebSearchTool,
         ComputerTool,
+        WebSearchTool,
         Mcp,
         CodeInterpreter,
         ImageGeneration,
         LocalShell,
         CustomTool,
+        web_search_tool.WebSearchTool,
     ],
     PropertyInfo(discriminator="type"),
 ]