1"""OpenAI chat wrapper.23!!! warning "API scope"45 `ChatOpenAI` targets6 [official OpenAI API specifications](https://github.com/openai/openai-openapi)7 only. Non-standard response fields added by third-party providers (e.g.,8 `reasoning_content`, `reasoning_details`) are **not** extracted or9 preserved. If you are pointing `base_url` at a provider such as10 OpenRouter, vLLM, or DeepSeek, use the corresponding provider-specific11 LangChain package instead (e.g., `ChatDeepSeek`, `ChatOpenRouter`).12"""1314from __future__ import annotations1516import base6417import json18import logging19import os20import re21import ssl22import sys23import warnings24from collections.abc import (25 AsyncIterator,26 Awaitable,27 Callable,28 Iterator,29 Mapping,30 Sequence,31)32from functools import partial33from io import BytesIO34from json import JSONDecodeError35from math import ceil36from operator import itemgetter37from typing import (38 TYPE_CHECKING,39 Any,40 Literal,41 Self,42 TypeAlias,43 TypeVar,44 cast,45)46from urllib.parse import urlparse4748import certifi49import openai50import tiktoken51from langchain_core.callbacks import (52 AsyncCallbackManagerForLLMRun,53 CallbackManagerForLLMRun,54)55from langchain_core.exceptions import (56 ContextOverflowError,57 ModelAPIError,58 ModelAuthenticationError,59 ModelConnectionError,60 ModelInvalidRequestError,61 ModelNotFoundError,62 ModelPermissionDeniedError,63 ModelRateLimitError,64 ModelRefusalError,65 ModelTimeoutError,66)67from langchain_core.language_models import (68 LanguageModelInput,69 ModelProfileRegistry,70)71from langchain_core.language_models.chat_models import (72 BaseChatModel,73 LangSmithParams,74)75from langchain_core.messages import (76 AIMessage,77 AIMessageChunk,78 BaseMessage,79 BaseMessageChunk,80 ChatMessage,81 ChatMessageChunk,82 FunctionMessage,83 FunctionMessageChunk,84 HumanMessage,85 HumanMessageChunk,86 InvalidToolCall,87 SystemMessage,88 SystemMessageChunk,89 ToolCall,90 ToolMessage,91 ToolMessageChunk,92 is_data_content_block,93)94from langchain_core.messages import content as types95from langchain_core.messages.ai import (96 InputTokenDetails,97 OutputTokenDetails,98 UsageMetadata,99)100from langchain_core.messages.block_translators.openai import (101 _convert_from_v03_ai_message,102 convert_to_openai_data_block,103)104from langchain_core.messages.tool import tool_call_chunk105from langchain_core.output_parsers import JsonOutputParser, PydanticOutputParser106from langchain_core.output_parsers.openai_tools import (107 JsonOutputKeyToolsParser,108 PydanticToolsParser,109 make_invalid_tool_call,110 parse_tool_call,111)112from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult113from langchain_core.runnables import (114 Runnable,115 RunnableGenerator,116 RunnableLambda,117 RunnableMap,118 RunnablePassthrough,119)120from langchain_core.runnables.config import run_in_executor121from langchain_core.tools import BaseTool122from langchain_core.tools.base import _stringify123from langchain_core.utils import get_pydantic_field_names124from langchain_core.utils._gateway import (125 GATEWAY_METADATA_RESPONSE_KEY,126 _gateway_headers,127 _langsmith_gateway_active,128 _parse_gateway_metadata,129 _resolve_gateway_config,130 _with_gateway_headers,131)132from langchain_core.utils.function_calling import (133 convert_to_openai_function,134 convert_to_openai_tool,135)136from langchain_core.utils.pydantic import (137 PydanticBaseModel,138 TypeBaseModel,139 is_basemodel_subclass,140)141from langchain_core.utils.utils import LC_AUTO_PREFIX, _build_model_kwargs, from_env142from pydantic import (143 BaseModel,144 ConfigDict,145 Field,146 PrivateAttr,147 SecretStr,148 ValidationError,149 field_validator,150 model_validator,151)152from pydantic.v1 import BaseModel as BaseModelV1153154from langchain_openai._version import __version__155from langchain_openai.chat_models._client_utils import (156 _astream_with_chunk_timeout,157 _build_proxied_async_httpx_client,158 _build_proxied_sync_httpx_client,159 _float_env,160 _get_default_async_httpx_client,161 _get_default_httpx_client,162 _log_proxy_env_bypass_once,163 _resolve_socket_options,164 _resolve_sync_and_async_api_keys,165 _should_bypass_socket_options_for_proxy_env,166 _warn_if_proxy_env_shadowed,167)168from langchain_openai.chat_models._compat import (169 _convert_from_v1_to_chat_completions,170 _convert_from_v1_to_responses,171 _convert_to_v03_ai_message,172 _unwrap_non_standard,173)174from langchain_openai.data._profiles import _PROFILES175176if TYPE_CHECKING:177 import httpx178 from langchain_core.language_models import ModelProfile179 from openai.types.responses import Response180181logger = logging.getLogger(__name__)182183# This SSL context is equivalent to the default `verify=True`.184# https://www.python-httpx.org/advanced/ssl/#configuring-client-instances185global_ssl_context = ssl.create_default_context(cafile=certifi.where())186187_ssrf_client: httpx.Client | None = None188189190def _get_ssrf_safe_client() -> httpx.Client:191 global _ssrf_client192 if _ssrf_client is None:193 from langchain_core._security._transport import ssrf_safe_client194195 _ssrf_client = ssrf_safe_client(196 verify=global_ssl_context, follow_redirects=False197 )198 return _ssrf_client199200201_MODEL_PROFILES = cast(ModelProfileRegistry, _PROFILES)202203204def _get_default_model_profile(model_name: str) -> ModelProfile:205 default = _MODEL_PROFILES.get(model_name) or {}206 return default.copy()207208209WellKnownTools = (210 "file_search",211 "web_search_preview",212 "web_search",213 "computer_use_preview",214 "code_interpreter",215 "mcp",216 "image_generation",217 "tool_search",218 "apply_patch",219)220221_TOOL_EXTRAS_PASSTHROUGH = ("defer_loading", "async")222223224def _convert_dict_to_message(_dict: Mapping[str, Any]) -> BaseMessage:225 """Convert a dictionary to a LangChain message.226227 Args:228 _dict: The dictionary.229230 Returns:231 The LangChain message.232 """233 role = _dict.get("role")234 name = _dict.get("name")235 id_ = _dict.get("id")236 if role == "user":237 return HumanMessage(content=_dict.get("content", ""), id=id_, name=name)238 if role == "assistant":239 # Fix for azure240 # Also OpenAI returns None for tool invocations241 content = _dict.get("content", "") or ""242 additional_kwargs: dict = {}243 if function_call := _dict.get("function_call"):244 additional_kwargs["function_call"] = dict(function_call)245 tool_calls = []246 invalid_tool_calls = []247 if raw_tool_calls := _dict.get("tool_calls"):248 for raw_tool_call in raw_tool_calls:249 try:250 tool_calls.append(parse_tool_call(raw_tool_call, return_id=True))251 except Exception as e:252 invalid_tool_calls.append(253 make_invalid_tool_call(raw_tool_call, str(e))254 )255 if audio := _dict.get("audio"):256 additional_kwargs["audio"] = audio257 if refusal := _dict.get("refusal"):258 additional_kwargs["refusal"] = refusal259 return AIMessage(260 content=content,261 additional_kwargs=additional_kwargs,262 name=name,263 id=id_,264 tool_calls=tool_calls,265 invalid_tool_calls=invalid_tool_calls,266 )267 if role in ("system", "developer"):268 additional_kwargs = {"__openai_role__": role} if role == "developer" else {}269 return SystemMessage(270 content=_dict.get("content", ""),271 name=name,272 id=id_,273 additional_kwargs=additional_kwargs,274 )275 if role == "function":276 return FunctionMessage(277 content=_dict.get("content", ""), name=cast(str, _dict.get("name")), id=id_278 )279 if role == "tool":280 additional_kwargs = {}281 if "name" in _dict:282 additional_kwargs["name"] = _dict["name"]283 return ToolMessage(284 content=_dict.get("content", ""),285 tool_call_id=cast(str, _dict.get("tool_call_id")),286 additional_kwargs=additional_kwargs,287 name=name,288 id=id_,289 )290 return ChatMessage(content=_dict.get("content", ""), role=role, id=id_) # type: ignore[arg-type]291292293def _apply_prompt_cache_breakpoint(294 source_block: dict[str, Any], formatted_block: dict[str, Any]295) -> dict[str, Any]:296 """Apply an OpenAI prompt cache breakpoint to a formatted content block.297298 A breakpoint set directly on the block takes precedence over one nested in299 `extras`. Membership (not truthiness) decides whether to copy it, so a300 present-but-falsy value (e.g. `None`) is still preserved.301 """302 if "prompt_cache_breakpoint" in source_block:303 formatted_block["prompt_cache_breakpoint"] = source_block[304 "prompt_cache_breakpoint"305 ]306 elif isinstance(extras := source_block.get("extras"), dict) and (307 "prompt_cache_breakpoint" in extras308 ):309 formatted_block["prompt_cache_breakpoint"] = extras["prompt_cache_breakpoint"]310 return formatted_block311312313def _sanitize_chat_completions_content(content: str | list[dict]) -> str | list[dict]:314 """Sanitize content for chat/completions API.315316 For list content, filters text blocks to only keep supported keys.317 """318 if isinstance(content, list):319 sanitized = []320 for block in content:321 if (322 isinstance(block, dict)323 and block.get("type") == "text"324 and "text" in block325 ):326 sanitized_block = {"type": "text", "text": block["text"]}327 if "prompt_cache_breakpoint" in block:328 sanitized_block["prompt_cache_breakpoint"] = block[329 "prompt_cache_breakpoint"330 ]331 sanitized.append(sanitized_block)332 else:333 sanitized.append(block)334 return sanitized335 return content336337338_ADDITIONAL_TOOLS_BLOCK_TYPE = "additional_tools"339"""Responses API input item that adds tools partway through a conversation."""340341342def _is_ai_role(role: str | None) -> bool:343 """Return whether a message's role is the assistant's.344345 Assistant content is replayed model output, not a caller's instruction, so it is346 exempt from the placement checks a caller's own blocks are held to.347 """348 return str(role).lower().startswith("ai")349350351def _is_system_role(role: str | None) -> bool:352 """Return whether a message's role carries provider instructions.353354 `SystemMessage` reports `"system"` whether or not it is later emitted with355 OpenAI's `developer` role, so one check covers both spellings.356 """357 return role in ("system", "developer")358359360def _raise_if_additional_tools(content: Any, reason: str) -> None:361 """Reject an `additional_tools` block that cannot work where it was placed.362363 The block only reaches the wire as a Responses top-level input item carried on364 a system message. Anywhere else it is this provider's own block type in a365 position this provider forbids, which the error taxonomy makes loud rather than366 silent: nothing routes a request to the Responses API based on message content,367 so a silent drop would make the broken case the default outcome.368369 Args:370 content: The message's content.371 reason: Sentence explaining why this placement cannot work, and how to fix372 it. Appended to the error.373374 Raises:375 ValueError: If an `additional_tools` block is present, in either spelling.376 """377 if not isinstance(content, list):378 return379 for raw_block in content:380 if (381 isinstance(raw_block, dict)382 and _unwrap_non_standard(raw_block).get("type")383 == _ADDITIONAL_TOOLS_BLOCK_TYPE384 ):385 msg = f"`additional_tools` {reason}"386 raise ValueError(msg)387388389def _format_message_content(390 content: Any,391 api: Literal["chat/completions", "responses"] = "chat/completions",392 role: str | None = None,393) -> Any:394 """Format message content."""395 if _is_ai_role(role):396 # Replayed assistant output; `additional_tools` is also an output item, so397 # an echoed one must survive a round trip rather than abort the request.398 pass399 elif not _is_system_role(role):400 _raise_if_additional_tools(401 content,402 "must be carried on a `SystemMessage`. OpenAI restricts the input item "403 'to `role: "developer"`, so it cannot be sent on any other message.',404 )405 elif api == "chat/completions":406 _raise_if_additional_tools(407 content,408 "requires the Responses API and cannot be sent via Chat Completions. "409 "Set `use_responses_api=True`.",410 )411 if content and isinstance(content, list):412 formatted_content = []413 for block in content:414 # Remove unexpected block types415 if (416 isinstance(block, dict)417 and "type" in block418 and (419 block["type"] in ("tool_use", "thinking", "reasoning_content")420 or (421 block["type"] in ("function_call", "code_interpreter_call")422 and api == "chat/completions"423 )424 )425 ):426 continue427 if (428 isinstance(block, dict)429 and is_data_content_block(block)430 # Responses API messages handled separately in _compat (parsed into431 # image generation calls)432 and not (api == "responses" and str(role).lower().startswith("ai"))433 ):434 formatted_block = convert_to_openai_data_block(block, api=api)435 formatted_content.append(436 _apply_prompt_cache_breakpoint(block, formatted_block)437 )438 elif (439 isinstance(block, dict)440 and block.get("type") == "text"441 and "text" in block442 and isinstance(extras := block.get("extras"), dict)443 and "prompt_cache_breakpoint" in extras444 ):445 formatted_block = {"type": "text", "text": block["text"]}446 formatted_content.append(447 _apply_prompt_cache_breakpoint(block, formatted_block)448 )449 # Anthropic image blocks450 elif (451 isinstance(block, dict)452 and block.get("type") == "image"453 and (source := block.get("source"))454 and isinstance(source, dict)455 ):456 if source.get("type") == "base64" and (457 (media_type := source.get("media_type"))458 and (data := source.get("data"))459 ):460 formatted_content.append(461 {462 "type": "image_url",463 "image_url": {"url": f"data:{media_type};base64,{data}"},464 }465 )466 elif source.get("type") == "url" and (url := source.get("url")):467 formatted_content.append(468 {"type": "image_url", "image_url": {"url": url}}469 )470 else:471 continue472 else:473 formatted_content.append(block)474 else:475 formatted_content = content476477 return formatted_content478479480def _convert_message_to_dict(481 message: BaseMessage,482 api: Literal["chat/completions", "responses"] = "chat/completions",483) -> dict:484 """Convert a LangChain message to dictionary format expected by OpenAI."""485 message_dict: dict[str, Any] = {486 "content": _format_message_content(message.content, api=api, role=message.type)487 }488 if (name := message.name or message.additional_kwargs.get("name")) is not None:489 message_dict["name"] = name490491 # populate role and additional message data492 if isinstance(message, ChatMessage):493 message_dict["role"] = message.role494 elif isinstance(message, HumanMessage):495 message_dict["role"] = "user"496 elif isinstance(message, AIMessage):497 message_dict["role"] = "assistant"498 if message.tool_calls or message.invalid_tool_calls:499 message_dict["tool_calls"] = [500 _lc_tool_call_to_openai_tool_call(tc) for tc in message.tool_calls501 ] + [502 _lc_invalid_tool_call_to_openai_tool_call(tc)503 for tc in message.invalid_tool_calls504 ]505 elif "tool_calls" in message.additional_kwargs:506 message_dict["tool_calls"] = message.additional_kwargs["tool_calls"]507 tool_call_supported_props = {"id", "type", "function"}508 message_dict["tool_calls"] = [509 {k: v for k, v in tool_call.items() if k in tool_call_supported_props}510 for tool_call in message_dict["tool_calls"]511 ]512 elif "function_call" in message.additional_kwargs:513 # OpenAI raises 400 if both function_call and tool_calls are present in the514 # same message.515 message_dict["function_call"] = message.additional_kwargs["function_call"]516 else:517 pass518 # If tool calls present, content null value should be None not empty string.519 if "function_call" in message_dict or "tool_calls" in message_dict:520 message_dict["content"] = message_dict["content"] or None521522 audio: dict[str, Any] | None = None523 for block in message.content:524 if (525 isinstance(block, dict)526 and block.get("type") == "audio"527 and (id_ := block.get("id"))528 and api != "responses"529 ):530 # openai doesn't support passing the data back - only the id531 # https://platform.openai.com/docs/guides/audio/multi-turn-conversations532 audio = {"id": id_}533 if not audio and "audio" in message.additional_kwargs:534 raw_audio = message.additional_kwargs["audio"]535 audio = (536 {"id": message.additional_kwargs["audio"]["id"]}537 if "id" in raw_audio538 else raw_audio539 )540 if audio:541 message_dict["audio"] = audio542 elif isinstance(message, SystemMessage):543 message_dict["role"] = message.additional_kwargs.get(544 "__openai_role__", "system"545 )546 elif isinstance(message, FunctionMessage):547 message_dict["role"] = "function"548 elif isinstance(message, ToolMessage):549 message_dict["role"] = "tool"550 message_dict["tool_call_id"] = message.tool_call_id551 message_dict["content"] = _sanitize_chat_completions_content(552 message_dict["content"]553 )554 supported_props = {"content", "role", "tool_call_id"}555 message_dict = {k: v for k, v in message_dict.items() if k in supported_props}556 else:557 msg = f"Got unknown type {message}"558 raise TypeError(msg)559 return message_dict560561562def _convert_delta_to_message_chunk(563 _dict: Mapping[str, Any], default_class: type[BaseMessageChunk]564) -> BaseMessageChunk:565 """Convert to a LangChain message chunk."""566 id_ = _dict.get("id")567 role = cast(str, _dict.get("role"))568 content = cast(str, _dict.get("content") or "")569 additional_kwargs: dict = {}570 if _dict.get("function_call"):571 function_call = dict(_dict["function_call"])572 if "name" in function_call and function_call["name"] is None:573 function_call["name"] = ""574 additional_kwargs["function_call"] = function_call575 tool_call_chunks = []576 if raw_tool_calls := _dict.get("tool_calls"):577 try:578 tool_call_chunks = [579 tool_call_chunk(580 name=rtc["function"].get("name"),581 args=rtc["function"].get("arguments"),582 id=rtc.get("id"),583 index=rtc["index"],584 )585 for rtc in raw_tool_calls586 ]587 except KeyError:588 pass589590 if role == "user" or default_class == HumanMessageChunk:591 return HumanMessageChunk(content=content, id=id_)592 if role == "assistant" or default_class == AIMessageChunk:593 return AIMessageChunk(594 content=content,595 additional_kwargs=additional_kwargs,596 id=id_,597 tool_call_chunks=tool_call_chunks, # type: ignore[arg-type]598 )599 if role in ("system", "developer") or default_class == SystemMessageChunk:600 if role == "developer":601 additional_kwargs = {"__openai_role__": "developer"}602 else:603 additional_kwargs = {}604 return SystemMessageChunk(605 content=content, id=id_, additional_kwargs=additional_kwargs606 )607 if role == "function" or default_class == FunctionMessageChunk:608 return FunctionMessageChunk(content=content, name=_dict["name"], id=id_)609 if role == "tool" or default_class == ToolMessageChunk:610 return ToolMessageChunk(611 content=content, tool_call_id=_dict["tool_call_id"], id=id_612 )613 if role or default_class == ChatMessageChunk:614 return ChatMessageChunk(content=content, role=role, id=id_)615 return default_class(content=content, id=id_) # type: ignore[call-arg]616617618def _update_token_usage(619 overall_token_usage: int | dict, new_usage: int | dict620) -> int | dict:621 # Token usage is either ints or dictionaries622 # `reasoning_tokens` is nested inside `completion_tokens_details`623 if isinstance(new_usage, int):624 if not isinstance(overall_token_usage, int):625 msg = (626 f"Got different types for token usage: "627 f"{type(new_usage)} and {type(overall_token_usage)}"628 )629 raise ValueError(msg)630 return new_usage + overall_token_usage631 if isinstance(new_usage, dict):632 if not isinstance(overall_token_usage, dict):633 msg = (634 f"Got different types for token usage: "635 f"{type(new_usage)} and {type(overall_token_usage)}"636 )637 raise ValueError(msg)638 return {639 k: _update_token_usage(overall_token_usage.get(k, 0), v)640 for k, v in new_usage.items()641 }642 warnings.warn(f"Unexpected type for token usage: {type(new_usage)}")643 return new_usage644645646class OpenAIContextOverflowError(openai.BadRequestError, ContextOverflowError):647 """BadRequestError raised when input exceeds OpenAI's context limit."""648649650class OpenAIAPIContextOverflowError(openai.APIError, ContextOverflowError):651 """APIError raised when input exceeds OpenAI's context limit."""652653654class OpenAIAuthenticationError(openai.AuthenticationError, ModelAuthenticationError):655 """OpenAI authentication error classified as a LangChain model error."""656657658class OpenAIPermissionDeniedError(659 openai.PermissionDeniedError, ModelPermissionDeniedError660):661 """OpenAI permission error classified as a LangChain model error."""662663664class OpenAIInvalidRequestError(openai.BadRequestError, ModelInvalidRequestError):665 """OpenAI bad-request error classified as a LangChain model error."""666667668class OpenAIModelNotFoundError(openai.NotFoundError, ModelNotFoundError):669 """OpenAI not-found error classified as a LangChain model error."""670671672class OpenAIRateLimitError(openai.RateLimitError, ModelRateLimitError):673 """OpenAI rate-limit error classified as a LangChain model error."""674675676class OpenAIAPIError(openai.InternalServerError, ModelAPIError):677 """OpenAI server error classified as a LangChain model error."""678679680class OpenAIConnectionError(openai.APIConnectionError, ModelConnectionError):681 """OpenAI connection error classified as a LangChain model error."""682683684class OpenAITimeoutError(openai.APITimeoutError, ModelTimeoutError):685 """OpenAI timeout error classified as a LangChain model error."""686687688class OpenAIStreamServerError(openai.APIError, ModelAPIError):689 """OpenAI server error reported inside a stream, classified as retryable.690691 OpenAI can accept a streaming request with HTTP 200 and then fail partway692 through by sending an error event. The SDK raises these as a bare693 `openai.APIError` with no status code, so this class carries the same694 `ModelAPIError` classification an HTTP 5xx gets without fabricating an695 HTTP response.696 """697698699class OpenAIResponsesServerError(ValueError, ModelAPIError):700 """Responses API `response.failed` or `error` event with a server error code.701702 Subclasses `ValueError`, which these stream events raise for other codes.703 """704705706_TRANSIENT_STREAM_ERROR_CODES = frozenset({"server_error"})707"""In-band stream error codes/types that indicate a transient backend failure."""708709710def _handle_openai_bad_request(e: openai.BadRequestError) -> None:711 if (712 "context_length_exceeded" in str(e)713 or "Input tokens exceed the configured limit" in e.message714 or "prompt is too long" in e.message715 or "ContextWindowExceededError" in e.message716 ):717 raise OpenAIContextOverflowError(718 message=e.message, response=e.response, body=e.body719 ) from e720 if (721 "'response_format' of type 'json_schema' is not supported with this model"722 ) in e.message:723 message = (724 "This model does not support OpenAI's structured output feature, which "725 "is the default method for `with_structured_output` as of "726 "langchain-openai==0.3. To use `with_structured_output` with this model, "727 'specify `method="function_calling"`.'728 )729 warnings.warn(message)730 raise OpenAIInvalidRequestError(731 message=e.message, response=e.response, body=e.body732 ) from e733 if "Invalid schema for response_format" in e.message:734 message = (735 "Invalid schema for OpenAI's structured output feature, which is the "736 "default method for `with_structured_output` as of langchain-openai==0.3. "737 'Specify `method="function_calling"` instead or update your schema. '738 "See supported schemas: "739 "https://platform.openai.com/docs/guides/structured-outputs#supported-schemas"740 )741 warnings.warn(message)742 raise OpenAIInvalidRequestError(743 message=e.message, response=e.response, body=e.body744 ) from e745746747def _handle_openai_api_error(e: openai.APIError) -> None:748 error_message = str(e)749 if "exceeds the context window" in error_message:750 raise OpenAIAPIContextOverflowError(751 message=e.message, request=e.request, body=e.body752 ) from e753 if isinstance(e, openai.AuthenticationError):754 raise OpenAIAuthenticationError(755 message=e.message, response=e.response, body=e.body756 ) from e757 if isinstance(e, openai.PermissionDeniedError):758 raise OpenAIPermissionDeniedError(759 message=e.message, response=e.response, body=e.body760 ) from e761 if isinstance(e, openai.NotFoundError):762 raise OpenAIModelNotFoundError(763 message=e.message, response=e.response, body=e.body764 ) from e765 if isinstance(e, openai.RateLimitError):766 raise OpenAIRateLimitError(767 message=e.message, response=e.response, body=e.body768 ) from e769 if isinstance(e, openai.InternalServerError):770 raise OpenAIAPIError(message=e.message, response=e.response, body=e.body) from e771 if isinstance(e, openai.APITimeoutError):772 raise OpenAITimeoutError(e.request) from e773 if isinstance(e, openai.APIConnectionError):774 raise OpenAIConnectionError(message=e.message, request=e.request) from e775 # The SDK raises the exact `APIError` for an error event inside a stream that776 # already returned HTTP 200; subclasses carry their own status-based verdicts.777 if type(e) is openai.APIError and not _TRANSIENT_STREAM_ERROR_CODES.isdisjoint(778 (e.code, e.type)779 ):780 raise OpenAIStreamServerError(781 message=e.message, request=e.request, body=e.body782 ) from e783 raise784785786def _add_gateway_metadata(generation_info: dict[str, Any], raw_response: Any) -> None:787 """Add parsed LangSmith gateway metadata to `generation_info`, if present.788789 Args:790 generation_info: Generation info to mutate in place.791 raw_response: The raw provider response, or None.792 """793 headers = getattr(raw_response, "headers", None)794 if headers is None:795 return796 gateway_metadata = _parse_gateway_metadata(headers)797 if gateway_metadata is not None:798 generation_info[GATEWAY_METADATA_RESPONSE_KEY] = gateway_metadata799800801_RESPONSES_API_ONLY_PREFIXES = (802 "gpt-5-pro",803 "gpt-5.2-pro",804 "gpt-5.4-pro",805 "gpt-5.5-pro",806 "gpt-5.6-sol",807)808809810def _model_prefers_responses_api(model_name: str | None) -> bool:811 if not model_name:812 return False813 return model_name.startswith(_RESPONSES_API_ONLY_PREFIXES) or "codex" in model_name814815816_BM = TypeVar("_BM", bound=BaseModel)817_DictOrPydanticClass: TypeAlias = dict[str, Any] | type[_BM] | type818_DictOrPydantic: TypeAlias = dict | _BM819820821class BaseChatOpenAI(BaseChatModel):822 """Base wrapper around OpenAI large language models for chat.823824 This base class targets825 [official OpenAI API specifications](https://github.com/openai/openai-openapi)826 only. Non-standard response fields added by third-party providers (e.g.,827 `reasoning_content`) are not extracted. Use a provider-specific subclass for828 full provider support.829 """830831 client: Any = Field(default=None, exclude=True)832833 async_client: Any = Field(default=None, exclude=True)834835 root_client: Any = Field(default=None, exclude=True)836837 root_async_client: Any = Field(default=None, exclude=True)838839 model_name: str = Field(default="gpt-3.5-turbo", alias="model")840 """Model name to use."""841842 temperature: float | None = None843 """What sampling temperature to use."""844845 model_kwargs: dict[str, Any] = Field(default_factory=dict)846 """Holds any model parameters valid for `create` call not explicitly specified."""847848 openai_api_key: (849 SecretStr | Callable[[], str] | Callable[[], Awaitable[str]] | None850 ) = Field(alias="api_key", default=None)851 """API key to use.852853 Can be inferred from the `OPENAI_API_KEY` environment variable, or specified854 as a string, or sync or async callable that returns a string.855856 ??? example "Specify with environment variable"857858 ```bash859 export OPENAI_API_KEY=...860 ```861 ```python862 from langchain_openai import ChatOpenAI863864 model = ChatOpenAI(model="gpt-5-nano")865 ```866867 ??? example "Specify with a string"868869 ```python870 from langchain_openai import ChatOpenAI871872 model = ChatOpenAI(model="gpt-5-nano", api_key="...")873 ```874875 ??? example "Specify with a sync callable"876877 ```python878 from langchain_openai import ChatOpenAI879880 def get_api_key() -> str:881 # Custom logic to retrieve API key882 return "..."883884 model = ChatOpenAI(model="gpt-5-nano", api_key=get_api_key)885 ```886887 ??? example "Specify with an async callable"888889 ```python890 from langchain_openai import ChatOpenAI891892 async def get_api_key() -> str:893 # Custom async logic to retrieve API key894 return "..."895896 model = ChatOpenAI(model="gpt-5-nano", api_key=get_api_key)897 ```898 """899900 openai_api_base: str | None = Field(default=None, alias="base_url")901 """Base URL path for API requests, leave blank if not using a proxy or service emulator.902903 Resolution order (first match wins):904905 1. Explicit `base_url` (or `openai_api_base`) kwarg.906 2. Env var `OPENAI_API_BASE` (read by LangChain at init).907 3. Env var `OPENAI_BASE_URL` (read by the underlying `openai` SDK client).908909 `OPENAI_BASE_URL` is also inspected by LangChain only to decide whether to910 default-enable `stream_usage` — when set, the default is left off because many911 non-OpenAI endpoints do not support streaming token usage.912 """ # noqa: E501913914 openai_organization: str | None = Field(default=None, alias="organization")915 """Automatically inferred from env var `OPENAI_ORG_ID` if not provided."""916917 # to support explicit proxy for OpenAI918 openai_proxy: str | None = Field(919 default_factory=from_env("OPENAI_PROXY", default=None)920 )921922 request_timeout: float | tuple[float, float] | Any | None = Field(923 default=None, alias="timeout"924 )925 """Timeout for requests to OpenAI completion API.926927 Can be float, `httpx.Timeout` or `None`.928 """929930 stream_usage: bool | None = None931 """Whether to include usage metadata in streaming output.932933 If enabled, an additional message chunk will be generated during the stream934 including usage metadata.935936 This parameter is enabled unless `openai_api_base` is set or the model is937 initialized with a custom client, as many chat completions APIs do not938 support streaming token usage.939940 !!! version-added "Added in `langchain-openai` 0.3.9"941942 !!! warning "Behavior changed in `langchain-openai` 0.3.35"943944 Enabled for default base URL and client.945 """946947 max_retries: int | None = None948 """Maximum number of retries to make when generating."""949950 presence_penalty: float | None = None951 """Penalizes repeated tokens."""952953 frequency_penalty: float | None = None954 """Penalizes repeated tokens according to frequency."""955956 seed: int | None = None957 """Seed for generation"""958959 logprobs: bool | None = None960 """Whether to return logprobs."""961962 top_logprobs: int | None = None963 """Number of most likely tokens to return at each token position, each with an964 associated log probability.965966 `logprobs` must be set to true if this parameter is used.967 """968969 logit_bias: dict[int, int] | None = None970 """Modify the likelihood of specified tokens appearing in the completion."""971972 streaming: bool = False973 """Whether to stream the results or not."""974975 n: int | None = None976 """Number of chat completions to generate for each prompt."""977978 top_p: float | None = None979 """Total probability mass of tokens to consider at each step."""980981 max_tokens: int | None = Field(default=None)982 """Maximum number of tokens to generate."""983984 reasoning_effort: str | None = None985 """Constrains effort on reasoning for reasoning models.986987 For use with the Chat Completions API. Reasoning models only.988989 Currently supported values are `'minimal'`, `'low'`, `'medium'`, and990 `'high'`. Reducing reasoning effort can result in faster responses and fewer991 tokens used on reasoning in a response.992993 !!! note "Changing reasoning effort mid-conversation"994995 Changing this value part-way through a conversation changes a request-level996 parameter, which invalidates the cached prompt prefix.997998 Models that support it (currently GPT-6) can instead carry the new effort999 in a `configuration_update` item attached to the message that should start1000 using it:10011002 ```python1003 HumanMessage(1004 [1005 {"type": "configuration_update", "reasoning": {"effort": "high"}},1006 {"type": "text", "text": "Analyze the failure modes."},1007 ]1008 )1009 ```10101011 The new effort applies from that message onward, until another update1012 overrides it.1013 """10141015 reasoning: dict[str, Any] | None = None1016 """Reasoning parameters for reasoning models. None disables reasoning.10171018 For use with the Responses API.10191020 ```python1021 reasoning={1022 "effort": None, # Default None; can be "low", "medium", or "high"1023 "summary": "auto", # Can be "auto", "concise", or "detailed"1024 }1025 ```10261027 !!! version-added "Added in `langchain-openai` 0.3.24"1028 """10291030 verbosity: str | None = None1031 """Controls the verbosity level of responses for reasoning models.10321033 For use with the Responses API.10341035 Currently supported values are `'low'`, `'medium'`, and `'high'`.10361037 !!! version-added "Added in `langchain-openai` 0.3.28"1038 """10391040 tiktoken_model_name: str | None = None1041 """The model name to pass to tiktoken when using this class.10421043 Tiktoken is used to count the number of tokens in documents to constrain1044 them to be under a certain limit.10451046 By default, when set to `None`, this will be the same as the embedding model name.1047 However, there are some cases where you may want to use this `Embedding` class with1048 a model name not supported by tiktoken. This can include when using Azure embeddings1049 or when using one of the many model providers that expose an OpenAI-like1050 API but with different models. In those cases, in order to avoid erroring1051 when tiktoken is called, you can specify a model name to use here.1052 """10531054 default_headers: Mapping[str, str] | None = None10551056 _langsmith_gateway_headers: dict[str, str] | None = PrivateAttr(default=None)1057 """Headers from `langsmith_gateway`, sent by the client but never serialized."""10581059 default_query: Mapping[str, object] | None = None10601061 # Configure a custom httpx client. See the1062 # [httpx documentation](https://www.python-httpx.org/api/#client) for more details.1063 http_client: Any | None = Field(default=None, exclude=True)1064 """Optional `httpx.Client`.10651066 Only used for sync invocations. Must specify `http_async_client` as well if1067 you'd like a custom client for async invocations.1068 """10691070 http_async_client: Any | None = Field(default=None, exclude=True)1071 """Optional `httpx.AsyncClient`.10721073 Only used for async invocations. Must specify `http_client` as well if you'd1074 like a custom client for sync invocations.1075 """10761077 http_socket_options: Sequence[tuple[int, int, int]] | None = Field(1078 default=None, exclude=True1079 )1080 """TCP socket options applied to the httpx transports built by this instance.10811082 Defaults to a conservative TCP-keepalive + `TCP_USER_TIMEOUT` profile that1083 targets a ~2-minute bound on silent connection hangs (silent mid-stream peer1084 loss, gVisor/NAT idle timeouts, silent TCP black holes) on platforms that1085 support the full option set. On platforms that only support a subset1086 (macOS without `TCP_USER_TIMEOUT`, Windows with only `SO_KEEPALIVE`,1087 minimal kernels), unsupported options are silently dropped and the bound1088 degrades to whatever the remaining options + OS defaults provide — still1089 better than indefinite hang.10901091 Accepted values:10921093 - `None` (default): use env-driven defaults. Matches the "unset" convention1094 used by `http_client` elsewhere on this class.1095 - `()` (empty): disable socket-option injection entirely. Inherits the OS1096 defaults and restores httpx's native env-proxy auto-detection.1097 - A non-empty sequence of `(level, option, value)` tuples: explicit1098 override; passed verbatim to the transport (not filtered). Unsupported1099 options raise `OSError` at connect time rather than being silently1100 dropped — the user chose them explicitly.11011102 Environment variables (only consulted when this field is `None`):1103 `LANGCHAIN_OPENAI_TCP_KEEPALIVE` (set to `0` to disable entirely — the1104 kill-switch), `LANGCHAIN_OPENAI_TCP_KEEPIDLE`,1105 `LANGCHAIN_OPENAI_TCP_KEEPINTVL`, `LANGCHAIN_OPENAI_TCP_KEEPCNT`,1106 `LANGCHAIN_OPENAI_TCP_USER_TIMEOUT_MS`.11071108 Applied per side: if `http_client` is supplied, the sync path uses1109 that user-owned client's socket options as-is; the async path still1110 gets `http_socket_options` applied to its default builder (and1111 vice-versa for `http_async_client`). Supply both to take full control.11121113 !!! note "Interaction with env-proxy auto-detection"11141115 When a custom `httpx` transport is active, `httpx` disables its1116 native env-proxy auto-detection (`HTTP_PROXY` / `HTTPS_PROXY` /1117 `ALL_PROXY` / `NO_PROXY` and macOS/Windows system proxy settings).11181119 To keep the default shape safe, `ChatOpenAI` detects the1120 "proxy-env-shadow" pattern and **skips the custom transport1121 entirely** when **all** of the following hold:11221123 - `http_socket_options` is left at its default (`None`)1124 - No `http_client` or `http_async_client` supplied1125 - No `openai_proxy` supplied1126 - A proxy env var or system proxy is visible to httpx11271128 On that specific shape, the instance falls back to pre-PR behavior1129 and httpx's env-proxy auto-detection applies (a one-time `INFO` log1130 records the bypass for observability).11311132 If you explicitly set `http_socket_options=[...]` while a proxy1133 env var is also set, no bypass — you opted into the transport, and1134 a one-time `WARNING` records the shadowing. Set1135 `http_socket_options=()` or `LANGCHAIN_OPENAI_TCP_KEEPALIVE=0` to1136 disable transport injection explicitly, or pass a fully-configured1137 `http_async_client` / `http_client` to take full control. The1138 `openai_proxy` constructor kwarg is unaffected — socket options1139 are applied cleanly through the proxied transport on that path.1140 """11411142 stream_chunk_timeout: float | None = Field(1143 default_factory=lambda: _float_env(1144 "LANGCHAIN_OPENAI_STREAM_CHUNK_TIMEOUT_S", 120.01145 ),1146 exclude=True,1147 )1148 """Per-chunk wall-clock timeout (seconds) on async streaming responses.11491150 Applies to async invocations only (`astream`, `ainvoke` with streaming,1151 etc.). Sync streaming (`stream`) is not affected.11521153 Fires between content chunks yielded by the openai SDK's streaming iterator1154 (i.e., each call to `__anext__` on the response). Crucially, this is1155 **not** the same as httpx's `timeout.read`:11561157 - httpx's read timeout is inter-byte and gets reset every time *any* bytes1158 arrive on the socket — including OpenAI's SSE keepalive comments1159 (`: keepalive`) that trickle down during long model generations. A1160 stream that's silent on *content* but still producing keepalives looks1161 alive forever to httpx.1162 - `stream_chunk_timeout` measures the gap between *parsed chunks*. The1163 openai SDK's SSE parser consumes keepalive comments internally and does1164 not emit them as chunks, so keepalives do *not* reset this timer. It1165 fires on genuine content silence.11661167 When it fires, a `StreamChunkTimeoutError`1168 (subclass of `asyncio.TimeoutError`) is raised with a self-describing1169 message naming this knob, the env-var override, the model, and the1170 number of chunks received before the stall. A WARNING log with1171 `extra={"source": "stream_chunk_timeout", "timeout_s": <value>,1172 "model_name": <value>, "chunks_received": <value>}` also fires so1173 aggregate logging can distinguish app-layer timeouts from1174 transport-layer failures.11751176 Defaults to 120s. Set to `None` or `0` to disable. Overridable via the1177 `LANGCHAIN_OPENAI_STREAM_CHUNK_TIMEOUT_S` env var. Negative values1178 (from either the env var or the constructor kwarg — e.g., hydrated1179 from YAML/JSON configs) fall back to the default with a `WARNING` log1180 rather than silently disabling the wrapper, so a misconfigured value1181 still boots safely and the fallback is visible.1182 """11831184 stop: list[str] | str | None = Field(default=None, alias="stop_sequences")1185 """Default stop sequences."""11861187 extra_body: Mapping[str, Any] | None = None1188 """Optional additional JSON properties to include in the request parameters1189 when making requests to OpenAI compatible APIs, such as vLLM, LM Studio, or1190 other providers.11911192 This is the recommended way to pass custom parameters that are specific to your1193 OpenAI-compatible API provider but not part of the standard OpenAI API.11941195 Examples:1196 - [LM Studio](https://lmstudio.ai/) TTL parameter: `extra_body={"ttl": 300}`1197 - [vLLM](https://github.com/vllm-project/vllm) custom parameters:1198 `extra_body={"use_beam_search": True}`1199 - Any other provider-specific parameters12001201 !!! warning12021203 Do not use `model_kwargs` for custom parameters that are not part of the1204 standard OpenAI API, as this will cause errors when making API calls. Use1205 `extra_body` instead.1206 """12071208 include_response_headers: bool = False1209 """Whether to include response headers in the output message `response_metadata`.12101211 Note: some inference providers return additional metadata (such as served model1212 names) in the response headers. Enable to capture these metadata.1213 """12141215 disabled_params: dict[str, Any] | None = Field(default=None)1216 """Parameters of the OpenAI client or `chat.completions` endpoint that should be1217 disabled for the given model.12181219 Should be specified as `{"param": None | ['val1', 'val2']}` where the key is the1220 parameter and the value is either None, meaning that parameter should never be1221 used, or it's a list of disabled values for the parameter.12221223 For example, older models may not support the `'parallel_tool_calls'` parameter at1224 all, in which case `disabled_params={"parallel_tool_calls": None}` can be passed1225 in.12261227 If a parameter is disabled then it will not be used by default in any methods, e.g.1228 in `with_structured_output`. However this does not prevent a user from directly1229 passed in the parameter during invocation.1230 """12311232 context_management: list[dict[str, Any]] | None = None1233 """Configuration for1234 [context management](https://developers.openai.com/api/docs/guides/compaction).1235 """12361237 include: list[str] | None = None1238 """Additional fields to include in generations from Responses API.12391240 Supported values:12411242 - `'file_search_call.results'`1243 - `'message.input_image.image_url'`1244 - `'computer_call_output.output.image_url'`1245 - `'reasoning.encrypted_content'`1246 - `'code_interpreter_call.outputs'`12471248 !!! version-added "Added in `langchain-openai` 0.3.24"1249 """12501251 prompt_cache_options: dict[str, Any] | None = None1252 """Options controlling OpenAI prompt cache behavior.12531254 !!! version-added "Added in `langchain-openai` 1.3.5"1255 """12561257 service_tier: str | None = None1258 """Latency tier for request.12591260 Options are `'auto'`, `'default'`, or `'flex'`.12611262 Relevant for users of OpenAI's scale tier service.1263 """12641265 store: bool | None = None1266 """If `True`, OpenAI may store response data for future use.12671268 Defaults to `True` for the Responses API and `False` for the Chat Completions API.12691270 !!! version-added "Added in `langchain-openai` 0.3.24"1271 """12721273 truncation: str | None = None1274 """Truncation strategy (Responses API).12751276 Can be `'auto'` or `'disabled'` (default).12771278 If `'auto'`, model may drop input items from the middle of the message sequence to1279 fit the context window.12801281 !!! version-added "Added in `langchain-openai` 0.3.24"1282 """12831284 use_previous_response_id: bool = False1285 """If `True`, always pass `previous_response_id` using the ID of the most recent1286 response. Responses API only.12871288 Input messages up to the most recent response will be dropped from request1289 payloads.12901291 For example, the following two are equivalent:12921293 ```python1294 model = ChatOpenAI(1295 model="...",1296 use_previous_response_id=True,1297 )1298 model.invoke(1299 [1300 HumanMessage("Hello"),1301 AIMessage("Hi there!", response_metadata={"id": "resp_123"}),1302 HumanMessage("How are you?"),1303 ]1304 )1305 ```13061307 ```python1308 model = ChatOpenAI(model="...", use_responses_api=True)1309 model.invoke([HumanMessage("How are you?")], previous_response_id="resp_123")1310 ```13111312 !!! version-added "Added in `langchain-openai` 0.3.26"1313 """13141315 use_responses_api: bool | None = None1316 """Whether to use the Responses API instead of the Chat API.13171318 If not specified, set to `True` when instance settings require the Responses API,13191320 !!! version-added "Added in `langchain-openai` 0.3.9"1321 """13221323 output_version: str | None = Field(1324 default_factory=from_env("LC_OUTPUT_VERSION", default=None)1325 )1326 """Version of `AIMessage` output format to use.13271328 This field is used to roll-out new output formats for chat model `AIMessage`1329 responses in a backwards-compatible way.13301331 Supported values:13321333 - `'v0'`: `AIMessage` format as of `langchain-openai 0.3.x`.1334 - `'responses/v1'`: Formats Responses API output items into AIMessage content blocks1335 (Responses API only)1336 - `'v1'`: v1 of LangChain cross-provider standard.13371338 !!! warning "Behavior changed in `langchain-openai` 1.0.0"13391340 Default updated to `"responses/v1"`.1341 """13421343 model_config = ConfigDict(populate_by_name=True)13441345 @property1346 def _uses_gateway(self) -> bool:1347 """Whether requests are routed through the LangSmith gateway.13481349 Detected from the resolved API key: LangSmith keys (used to authenticate1350 to the gateway) carry the `lsv2_` prefix. Callable keys cannot be1351 inspected without invoking them, so they are treated as non-gateway.1352 """1353 api_key = self.openai_api_key1354 if isinstance(api_key, SecretStr):1355 return api_key.get_secret_value().startswith("lsv2_")1356 return False13571358 @property1359 def model(self) -> str:1360 """Same as model_name."""1361 return self.model_name13621363 @model_validator(mode="before")1364 @classmethod1365 def build_extra(cls, values: dict[str, Any]) -> Any:1366 """Build extra kwargs from additional params that were passed in."""1367 all_required_field_names = get_pydantic_field_names(cls)1368 return _build_model_kwargs(values, all_required_field_names)13691370 @field_validator("stream_chunk_timeout", mode="after")1371 @classmethod1372 def _validate_stream_chunk_timeout(cls, value: float | None) -> float | None:1373 """Reject negative constructor values; fall back to the env-driven default.13741375 Matches the env-var path in `_float_env`: a negative value is a typo,1376 not an opt-out (`None`/`0` are the documented off switches). Configs1377 hydrated from YAML/JSON would otherwise silently disable the wrapper1378 and reintroduce the indefinite-stream hang the feature prevents.1379 """1380 if value is not None and value < 0:1381 fallback = _float_env("LANGCHAIN_OPENAI_STREAM_CHUNK_TIMEOUT_S", 120.0)1382 logger.warning(1383 "Invalid `stream_chunk_timeout=%r` (negative); "1384 "falling back to %s. Pass `None` or `0` to disable.",1385 value,1386 fallback,1387 )1388 return fallback1389 return value13901391 @model_validator(mode="before")1392 @classmethod1393 def validate_temperature(cls, values: dict[str, Any]) -> Any:1394 """Validate temperature parameter for different models.13951396 - gpt-5 models (excluding gpt-5-chat) only allow `temperature=1` or unset1397 (Defaults to 1)1398 """1399 model = values.get("model_name") or values.get("model") or ""1400 model_lower = model.lower()14011402 # For o1 models, set temperature=1 if not provided1403 if model_lower.startswith("o1") and "temperature" not in values:1404 values["temperature"] = 114051406 # For gpt-5 models, handle temperature restrictions. Temperature is supported1407 # by gpt-5-chat and gpt-5 models with reasoning_effort='none' or1408 # reasoning={'effort': 'none'}.1409 if (1410 model_lower.startswith("gpt-5")1411 and ("chat" not in model_lower)1412 and values.get("reasoning_effort") != "none"1413 and (values.get("reasoning") or {}).get("effort") != "none"1414 ):1415 temperature = values.get("temperature")1416 if temperature is not None and temperature != 1:1417 # For gpt-5 (non-chat), only temperature=1 is supported1418 # So we remove any non-defaults1419 values.pop("temperature", None)14201421 return values14221423 @model_validator(mode="after")1424 def _set_openai_chat_version(self) -> Self:1425 """Set package version in metadata.14261427 Note: Subclasses that inherit from `BaseChatOpenAI` (e.g.1428 `ChatDeepSeek`, `ChatXAI`) must use a **unique** validator name1429 (e.g. `_set_deepseek_version`) instead of overriding this one. Pydantic1430 replaces same-named `model_validator` methods rather than chaining them,1431 so reusing `_set_openai_chat_version` would silently drop the parent's1432 `langchain-openai` version entry.1433 """1434 self._add_version("langchain-openai", __version__)1435 return self14361437 @model_validator(mode="after")1438 def _infer_use_responses_api(self) -> Self:1439 """Expose unconditional instance-level Responses API routing."""1440 if self.use_responses_api is None and self._use_responses_api({}):1441 self.use_responses_api = True1442 return self14431444 @model_validator(mode="after")1445 def validate_environment(self) -> Self:1446 """Validate that api key and python package exists in environment."""1447 if self.n is not None and self.n < 1:1448 msg = "n must be at least 1."1449 raise ValueError(msg)1450 if self.n is not None and self.n > 1 and self.streaming:1451 msg = "n must be 1 when streaming."1452 raise ValueError(msg)14531454 # Check OPENAI_ORGANIZATION for backwards compatibility.1455 self.openai_organization = (1456 self.openai_organization1457 or os.getenv("OPENAI_ORG_ID")1458 or os.getenv("OPENAI_ORGANIZATION")1459 )1460 # Resolve base URL and API key, applying LangSmith gateway settings.1461 _gateway_config = _resolve_gateway_config(1462 base_url=self.openai_api_base,1463 api_key=self.openai_api_key,1464 provider_path="openai/v1",1465 base_url_env="OPENAI_API_BASE",1466 api_key_env="OPENAI_API_KEY",1467 )1468 self.openai_api_base = _gateway_config.base_url1469 self.openai_api_key = _gateway_config.api_key1470 _base_url_from_gateway = _gateway_config.base_url_from_gateway1471 if _langsmith_gateway_active():1472 self.openai_proxy = None1473 if self._langsmith_gateway_headers is None:1474 self._langsmith_gateway_headers = _gateway_headers()14751476 # Enable stream_usage by default if using default base URL and client,1477 # or when the base URL was set by the LangSmith gateway (which proxies1478 # to OpenAI and supports streaming token usage).1479 if all(1480 getattr(self, key, None) is None1481 for key in (1482 "stream_usage",1483 "openai_proxy",1484 "client",1485 "root_client",1486 "async_client",1487 "root_async_client",1488 "http_client",1489 "http_async_client",1490 )1491 ) and (1492 _base_url_from_gateway1493 or (self.openai_api_base is None and "OPENAI_BASE_URL" not in os.environ)1494 ):1495 self.stream_usage = True14961497 # Resolve API key from SecretStr or Callable1498 sync_api_key_value: str | Callable[[], str] | None = None1499 async_api_key_value: str | Callable[[], Awaitable[str]] | None = None15001501 if self.openai_api_key is not None:1502 # Because OpenAI and AsyncOpenAI clients support either sync or async1503 # callables for the API key, we need to resolve separate values here.1504 sync_api_key_value, async_api_key_value = _resolve_sync_and_async_api_keys(1505 self.openai_api_key1506 )15071508 client_params: dict = {1509 "organization": self.openai_organization,1510 "base_url": self.openai_api_base,1511 "timeout": self.request_timeout,1512 "default_headers": _with_gateway_headers(1513 self.default_headers, self._langsmith_gateway_headers1514 ),1515 "default_query": self.default_query,1516 }1517 if self.max_retries is not None:1518 client_params["max_retries"] = self.max_retries15191520 if self.openai_proxy and (self.http_client or self.http_async_client):1521 openai_proxy = self.openai_proxy1522 http_client = self.http_client1523 http_async_client = self.http_async_client1524 msg = (1525 "Cannot specify 'openai_proxy' if one of "1526 "'http_client'/'http_async_client' is already specified. Received:\n"1527 f"{openai_proxy=}\n{http_client=}\n{http_async_client=}"1528 )1529 raise ValueError(msg)1530 if _should_bypass_socket_options_for_proxy_env(1531 http_socket_options=self.http_socket_options,1532 http_client=self.http_client,1533 http_async_client=self.http_async_client,1534 openai_proxy=self.openai_proxy,1535 ):1536 # Default-shape construction + proxy env var visible to httpx:1537 # skip the custom transport so httpx's env-proxy auto-detection1538 # still applies. Users who want kernel-level TCP tuning alongside1539 # an env proxy can opt in explicitly via `http_socket_options`.1540 resolved_socket_options: tuple[tuple[int, int, int], ...] = ()1541 _log_proxy_env_bypass_once()1542 else:1543 resolved_socket_options = _resolve_socket_options(self.http_socket_options)1544 _warn_if_proxy_env_shadowed(1545 resolved_socket_options, openai_proxy=self.openai_proxy1546 )1547 if not self.client:1548 if sync_api_key_value is None:1549 # No valid sync API key, leave client as None and raise informative1550 # error on invocation.1551 self.client = None1552 self.root_client = None1553 else:1554 if self.openai_proxy and not self.http_client:1555 self.http_client = _build_proxied_sync_httpx_client(1556 proxy=self.openai_proxy,1557 verify=global_ssl_context,1558 socket_options=resolved_socket_options,1559 )1560 sync_specific = {1561 "http_client": self.http_client1562 or _get_default_httpx_client(1563 self.openai_api_base,1564 self.request_timeout,1565 resolved_socket_options,1566 ),1567 "api_key": sync_api_key_value,1568 }1569 self.root_client = openai.OpenAI(**client_params, **sync_specific) # type: ignore[arg-type]1570 self.client = self.root_client.chat.completions1571 if not self.async_client:1572 if self.openai_proxy and not self.http_async_client:1573 self.http_async_client = _build_proxied_async_httpx_client(1574 proxy=self.openai_proxy,1575 verify=global_ssl_context,1576 socket_options=resolved_socket_options,1577 )1578 async_specific = {1579 "http_client": self.http_async_client1580 or _get_default_async_httpx_client(1581 self.openai_api_base,1582 self.request_timeout,1583 resolved_socket_options,1584 ),1585 "api_key": async_api_key_value,1586 }1587 self.root_async_client = openai.AsyncOpenAI(1588 **client_params,1589 **async_specific, # type: ignore[arg-type]1590 )1591 self.async_client = self.root_async_client.chat.completions1592 return self15931594 def _resolve_model_profile(self) -> ModelProfile | None:1595 profile = _get_default_model_profile(self.model_name) or None1596 if (1597 profile is not None1598 and profile.get("mid_conversation_tools")1599 and not self._use_responses_api({})1600 ):1601 # Only the Responses API carries an `additional_tools` input item.1602 # Routing that depends on the request can't be claimed up front.1603 profile["mid_conversation_tools"] = False1604 return profile16051606 @property1607 def _default_params(self) -> dict[str, Any]:1608 """Get the default parameters for calling OpenAI API."""1609 exclude_if_none = {1610 "presence_penalty": self.presence_penalty,1611 "frequency_penalty": self.frequency_penalty,1612 "seed": self.seed,1613 "top_p": self.top_p,1614 "logprobs": self.logprobs,1615 "top_logprobs": self.top_logprobs,1616 "logit_bias": self.logit_bias,1617 "stop": self.stop or None, # Also exclude empty list for this1618 "max_tokens": self.max_tokens,1619 "extra_body": self.extra_body,1620 "n": self.n,1621 "temperature": self.temperature,1622 "reasoning_effort": self.reasoning_effort,1623 "reasoning": self.reasoning,1624 "verbosity": self.verbosity,1625 "context_management": self.context_management,1626 "include": self.include,1627 "prompt_cache_options": self.prompt_cache_options,1628 "service_tier": self.service_tier,1629 "truncation": self.truncation,1630 "store": self.store,1631 }16321633 return {1634 "model": self.model_name,1635 "stream": self.streaming,1636 **{k: v for k, v in exclude_if_none.items() if v is not None},1637 **self.model_kwargs,1638 }16391640 def _combine_llm_outputs(self, llm_outputs: list[dict | None]) -> dict:1641 overall_token_usage: dict = {}1642 system_fingerprint = None1643 for output in llm_outputs:1644 if output is None:1645 # Happens in streaming1646 continue1647 token_usage = output.get("token_usage")1648 if token_usage is not None:1649 for k, v in token_usage.items():1650 if v is None:1651 continue1652 if k in overall_token_usage:1653 overall_token_usage[k] = _update_token_usage(1654 overall_token_usage[k], v1655 )1656 else:1657 overall_token_usage[k] = v1658 if system_fingerprint is None:1659 system_fingerprint = output.get("system_fingerprint")1660 combined = {"token_usage": overall_token_usage, "model_name": self.model_name}1661 if system_fingerprint:1662 combined["system_fingerprint"] = system_fingerprint1663 return combined16641665 def _convert_chunk_to_generation_chunk(1666 self,1667 chunk: dict,1668 default_chunk_class: type,1669 base_generation_info: dict | None,1670 ) -> ChatGenerationChunk | None:1671 if chunk.get("type") == "content.delta": # From beta.chat.completions.stream1672 return None1673 token_usage = chunk.get("usage")1674 choices = (1675 chunk.get("choices", [])1676 # From beta.chat.completions.stream1677 or chunk.get("chunk", {}).get("choices", [])1678 )16791680 usage_metadata: UsageMetadata | None = (1681 _create_usage_metadata(token_usage, chunk.get("service_tier"))1682 if token_usage1683 else None1684 )1685 if len(choices) == 0:1686 # logprobs is implicitly None1687 generation_chunk = ChatGenerationChunk(1688 message=default_chunk_class(content="", usage_metadata=usage_metadata),1689 generation_info=base_generation_info,1690 )1691 # Keep content as "" (the default) rather than converting to [].1692 # Chat Completions content deltas are normalized to strings in1693 # _convert_delta_to_message_chunk. Starting with [] causes1694 # merge_content to silently drop string content (empty list is1695 # falsy, so no merge branch applies). The empty list also triggers1696 # the content_blocks isinstance(list) short-circuit, which would1697 # return [] and miss tool_call_chunks.1698 if self.output_version == "v1":1699 generation_chunk.message.response_metadata["output_version"] = "v1"17001701 return generation_chunk17021703 choice = choices[0]1704 if choice["delta"] is None:1705 return None17061707 message_chunk = _convert_delta_to_message_chunk(1708 choice["delta"], default_chunk_class1709 )1710 generation_info = {**base_generation_info} if base_generation_info else {}17111712 if finish_reason := choice.get("finish_reason"):1713 generation_info["finish_reason"] = finish_reason1714 generation_info.update(_chat_finish_reason_fields(finish_reason))1715 if model_name := chunk.get("model"):1716 generation_info["model_name"] = model_name1717 if system_fingerprint := chunk.get("system_fingerprint"):1718 generation_info["system_fingerprint"] = system_fingerprint1719 if service_tier := chunk.get("service_tier"):1720 generation_info["service_tier"] = service_tier17211722 logprobs = choice.get("logprobs")1723 if logprobs:1724 generation_info["logprobs"] = logprobs17251726 if usage_metadata and isinstance(message_chunk, AIMessageChunk):1727 message_chunk.usage_metadata = usage_metadata17281729 message_chunk.response_metadata["model_provider"] = "openai"1730 # Propagate output_version so content_blocks can detect v1 mode.1731 if self.output_version == "v1":1732 message_chunk.response_metadata["output_version"] = "v1"1733 return ChatGenerationChunk(1734 message=message_chunk, generation_info=generation_info or None1735 )17361737 def _ensure_sync_client_available(self) -> None:1738 """Check that sync client is available, raise error if not."""1739 if self.client is None:1740 msg = (1741 "Sync client is not available. This happens when an async callable "1742 "was provided for the API key. Use async methods (ainvoke, astream) "1743 "instead, or provide a string or sync callable for the API key."1744 )1745 raise ValueError(msg)17461747 def _stream_responses(1748 self,1749 messages: list[BaseMessage],1750 stop: list[str] | None = None,1751 run_manager: CallbackManagerForLLMRun | None = None,1752 **kwargs: Any,1753 ) -> Iterator[ChatGenerationChunk]:1754 self._ensure_sync_client_available()1755 kwargs["stream"] = True1756 payload = self._get_request_payload(messages, stop=stop, **kwargs)1757 headers: dict = {}1758 base_generation_info: dict = {}1759 try:1760 if self.include_response_headers or self._uses_gateway:1761 raw_context_manager = (1762 self.root_client.with_raw_response.responses.create(**payload)1763 )1764 context_manager = raw_context_manager.parse()1765 if self.include_response_headers:1766 headers = {"headers": dict(raw_context_manager.headers)}1767 _add_gateway_metadata(base_generation_info, raw_context_manager)1768 else:1769 context_manager = self.root_client.responses.create(**payload)1770 original_schema_obj = kwargs.get("response_format")17711772 with context_manager as response:1773 is_first_chunk = True1774 current_index = -11775 current_output_index = -11776 current_sub_index = -11777 has_reasoning = False1778 item_output_indices: dict[str, int] = {}1779 function_call_arguments: dict[str, str] = {}1780 function_call_indices: dict[str, int] = {}1781 for chunk in response:1782 metadata = headers if is_first_chunk else {}1783 (1784 current_index,1785 current_output_index,1786 current_sub_index,1787 generation_chunk,1788 ) = _convert_responses_chunk_to_generation_chunk(1789 chunk,1790 current_index,1791 current_output_index,1792 current_sub_index,1793 schema=original_schema_obj,1794 metadata=metadata,1795 has_reasoning=has_reasoning,1796 output_version=self.output_version,1797 item_output_indices=item_output_indices,1798 function_call_arguments=function_call_arguments,1799 function_call_indices=function_call_indices,1800 )1801 if generation_chunk:1802 if is_first_chunk and base_generation_info:1803 generation_chunk.generation_info = {1804 **base_generation_info,1805 **(generation_chunk.generation_info or {}),1806 }1807 if run_manager:1808 run_manager.on_llm_new_token(1809 generation_chunk.text, chunk=generation_chunk1810 )1811 is_first_chunk = False1812 if "reasoning" in generation_chunk.message.additional_kwargs:1813 has_reasoning = True1814 yield generation_chunk1815 except openai.BadRequestError as e:1816 _handle_openai_bad_request(e)1817 except openai.APIError as e:1818 _handle_openai_api_error(e)18191820 async def _astream_responses(1821 self,1822 messages: list[BaseMessage],1823 stop: list[str] | None = None,1824 run_manager: AsyncCallbackManagerForLLMRun | None = None,1825 **kwargs: Any,1826 ) -> AsyncIterator[ChatGenerationChunk]:1827 kwargs["stream"] = True1828 payload = self._get_request_payload(messages, stop=stop, **kwargs)1829 headers: dict = {}1830 base_generation_info: dict = {}1831 try:1832 if self.include_response_headers or self._uses_gateway:1833 raw_context_manager = (1834 await self.root_async_client.with_raw_response.responses.create(1835 **payload1836 )1837 )1838 context_manager = raw_context_manager.parse()1839 if self.include_response_headers:1840 headers = {"headers": dict(raw_context_manager.headers)}1841 _add_gateway_metadata(base_generation_info, raw_context_manager)1842 else:1843 context_manager = await self.root_async_client.responses.create(1844 **payload1845 )1846 original_schema_obj = kwargs.get("response_format")18471848 async with context_manager as response:1849 is_first_chunk = True1850 current_index = -11851 current_output_index = -11852 current_sub_index = -11853 has_reasoning = False1854 item_output_indices: dict[str, int] = {}1855 function_call_arguments: dict[str, str] = {}1856 function_call_indices: dict[str, int] = {}1857 async for chunk in _astream_with_chunk_timeout(1858 response,1859 self.stream_chunk_timeout,1860 model_name=self.model_name,1861 ):1862 metadata = headers if is_first_chunk else {}1863 (1864 current_index,1865 current_output_index,1866 current_sub_index,1867 generation_chunk,1868 ) = _convert_responses_chunk_to_generation_chunk(1869 chunk,1870 current_index,1871 current_output_index,1872 current_sub_index,1873 schema=original_schema_obj,1874 metadata=metadata,1875 has_reasoning=has_reasoning,1876 output_version=self.output_version,1877 item_output_indices=item_output_indices,1878 function_call_arguments=function_call_arguments,1879 function_call_indices=function_call_indices,1880 )1881 if generation_chunk:1882 if is_first_chunk and base_generation_info:1883 generation_chunk.generation_info = {1884 **base_generation_info,1885 **(generation_chunk.generation_info or {}),1886 }1887 if run_manager:1888 await run_manager.on_llm_new_token(1889 generation_chunk.text, chunk=generation_chunk1890 )1891 is_first_chunk = False1892 if "reasoning" in generation_chunk.message.additional_kwargs:1893 has_reasoning = True1894 yield generation_chunk1895 except openai.BadRequestError as e:1896 _handle_openai_bad_request(e)1897 except openai.APIError as e:1898 _handle_openai_api_error(e)18991900 def _should_stream_usage(1901 self, stream_usage: bool | None = None, **kwargs: Any1902 ) -> bool:1903 """Determine whether to include usage metadata in streaming output.19041905 For backwards compatibility, we check for `stream_options` passed1906 explicitly to kwargs or in the `model_kwargs` and override `self.stream_usage`.1907 """1908 stream_usage_sources = [ # order of precedence1909 stream_usage,1910 kwargs.get("stream_options", {}).get("include_usage"),1911 self.model_kwargs.get("stream_options", {}).get("include_usage"),1912 self.stream_usage,1913 ]1914 for source in stream_usage_sources:1915 if isinstance(source, bool):1916 return source1917 return self.stream_usage or False19181919 def _stream(1920 self,1921 messages: list[BaseMessage],1922 stop: list[str] | None = None,1923 run_manager: CallbackManagerForLLMRun | None = None,1924 *,1925 stream_usage: bool | None = None,1926 **kwargs: Any,1927 ) -> Iterator[ChatGenerationChunk]:1928 self._ensure_sync_client_available()1929 kwargs["stream"] = True1930 stream_usage = self._should_stream_usage(stream_usage, **kwargs)1931 if stream_usage:1932 kwargs["stream_options"] = {"include_usage": stream_usage}1933 payload = self._get_request_payload(messages, stop=stop, **kwargs)1934 default_chunk_class: type[BaseMessageChunk] = AIMessageChunk1935 base_generation_info = {}19361937 try:1938 if "response_format" in payload:1939 if self.include_response_headers:1940 warnings.warn(1941 "Cannot currently include response headers when "1942 "response_format is specified."1943 )1944 payload.pop("stream")1945 response_stream = self.root_client.beta.chat.completions.stream(1946 **payload1947 )1948 context_manager = response_stream1949 else:1950 if self.include_response_headers or self._uses_gateway:1951 raw_response = self.client.with_raw_response.create(**payload)1952 response = raw_response.parse()1953 if self.include_response_headers:1954 base_generation_info = {"headers": dict(raw_response.headers)}1955 _add_gateway_metadata(base_generation_info, raw_response)1956 else:1957 response = self.client.create(**payload)1958 context_manager = response1959 with context_manager as response:1960 is_first_chunk = True1961 finish_tracker = _StreamFinishTracker()1962 for chunk in response:1963 if not isinstance(chunk, dict):1964 chunk = chunk.model_dump()1965 generation_chunk = self._convert_chunk_to_generation_chunk(1966 chunk,1967 default_chunk_class,1968 base_generation_info if is_first_chunk else {},1969 )1970 if generation_chunk is None:1971 continue1972 finish_tracker.update(chunk, generation_chunk)1973 default_chunk_class = generation_chunk.message.__class__1974 logprobs = (generation_chunk.generation_info or {}).get("logprobs")1975 if run_manager:1976 run_manager.on_llm_new_token(1977 generation_chunk.text,1978 chunk=generation_chunk,1979 logprobs=logprobs,1980 )1981 is_first_chunk = False1982 yield generation_chunk1983 except openai.BadRequestError as e:1984 _handle_openai_bad_request(e)1985 except openai.APIError as e:1986 _handle_openai_api_error(e)1987 if hasattr(response, "get_final_completion") and "response_format" in payload:1988 final_completion = response.get_final_completion()1989 generation_chunk = self._get_generation_chunk_from_completion(1990 final_completion1991 )1992 if run_manager:1993 run_manager.on_llm_new_token(1994 generation_chunk.text, chunk=generation_chunk1995 )1996 yield generation_chunk19971998 def _generate(1999 self,2000 messages: list[BaseMessage],
Findings
✓ No findings reported for this file.