The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
chore(core): fix some docstrings (#34426)
Christophe Bornet8bca31f8c4f2
diff --git a/libs/core/langchain_core/messages/block_translators/anthropic.py b/libs/core/langchain_core/messages/block_translators/anthropic.pyindex 7f514948bf..86ad0226d1 100644--- a/libs/core/langchain_core/messages/block_translators/anthropic.py+++ b/libs/core/langchain_core/messages/block_translators/anthropic.py@@ -465,12 +465,26 @@ def _convert_to_v1_from_anthropic(message: AIMessage) -> list[types.ContentBlockdef translate_content(message: AIMessage) -> list[types.ContentBlock]:- """Derive standard content blocks from a message with Anthropic content."""+ """Derive standard content blocks from a message with Anthropic content.++ Args:+ message: The message to translate.++ Returns:+ The derived content blocks.+ """return _convert_to_v1_from_anthropic(message)def translate_content_chunk(message: AIMessageChunk) -> list[types.ContentBlock]:- """Derive standard content blocks from a message chunk with Anthropic content."""+ """Derive standard content blocks from a message chunk with Anthropic content.++ Args:+ message: The message chunk to translate.++ Returns:+ The derived content blocks.+ """return _convert_to_v1_from_anthropic(message)diff --git a/libs/core/langchain_core/messages/block_translators/bedrock.py b/libs/core/langchain_core/messages/block_translators/bedrock.pyindex 481eeea8de..f37f223016 100644--- a/libs/core/langchain_core/messages/block_translators/bedrock.py+++ b/libs/core/langchain_core/messages/block_translators/bedrock.py@@ -65,14 +65,28 @@ def _convert_to_v1_from_bedrock_chunk(def translate_content(message: AIMessage) -> list[types.ContentBlock]:- """Derive standard content blocks from a message with Bedrock content."""+ """Derive standard content blocks from a message with Bedrock content.++ Args:+ message: The message to translate.++ Returns:+ The derived content blocks.+ """if "claude" not in message.response_metadata.get("model_name", "").lower():raise NotImplementedError # fall back to best-effort parsingreturn _convert_to_v1_from_bedrock(message)def translate_content_chunk(message: AIMessageChunk) -> list[types.ContentBlock]:- """Derive standard content blocks from a message chunk with Bedrock content."""+ """Derive standard content blocks from a message chunk with Bedrock content.++ Args:+ message: The message chunk to translate.++ Returns:+ The derived content blocks.+ """# TODO: add model_name to all Bedrock chunks and update core merging logic# to not append during aggregation. Then raise NotImplementedError here if# not an Anthropic model to fall back to best-effort parsing.diff --git a/libs/core/langchain_core/messages/block_translators/bedrock_converse.py b/libs/core/langchain_core/messages/block_translators/bedrock_converse.pyindex 226edc9de9..e6f9ae876d 100644--- a/libs/core/langchain_core/messages/block_translators/bedrock_converse.py+++ b/libs/core/langchain_core/messages/block_translators/bedrock_converse.py@@ -283,12 +283,26 @@ def _convert_to_v1_from_converse(message: AIMessage) -> list[types.ContentBlock]def translate_content(message: AIMessage) -> list[types.ContentBlock]:- """Derive standard content blocks from a message with Bedrock Converse content."""+ """Derive standard content blocks from a message with Bedrock Converse content.++ Args:+ message: The message to translate.++ Returns:+ The derived content blocks.+ """return _convert_to_v1_from_converse(message)def translate_content_chunk(message: AIMessageChunk) -> list[types.ContentBlock]:- """Derive standard content blocks from a chunk with Bedrock Converse content."""+ """Derive standard content blocks from a chunk with Bedrock Converse content.++ Args:+ message: The message chunk to translate.++ Returns:+ The derived content blocks.+ """return _convert_to_v1_from_converse(message)diff --git a/libs/core/langchain_core/messages/block_translators/google_genai.py b/libs/core/langchain_core/messages/block_translators/google_genai.pyindex 5e879b9128..da51ed74f6 100644--- a/libs/core/langchain_core/messages/block_translators/google_genai.py+++ b/libs/core/langchain_core/messages/block_translators/google_genai.py@@ -523,12 +523,26 @@ def _convert_to_v1_from_genai(message: AIMessage) -> list[types.ContentBlock]:def translate_content(message: AIMessage) -> list[types.ContentBlock]:- """Derive standard content blocks from a message with Google (GenAI) content."""+ """Derive standard content blocks from a message with Google (GenAI) content.++ Args:+ message: The message to translate.++ Returns:+ The derived content blocks.+ """return _convert_to_v1_from_genai(message)def translate_content_chunk(message: AIMessageChunk) -> list[types.ContentBlock]:- """Derive standard content blocks from a chunk with Google (GenAI) content."""+ """Derive standard content blocks from a chunk with Google (GenAI) content.++ Args:+ message: The message chunk to translate.++ Returns:+ The derived content blocks.+ """return _convert_to_v1_from_genai(message)diff --git a/libs/core/langchain_core/messages/block_translators/groq.py b/libs/core/langchain_core/messages/block_translators/groq.pyindex 33f1921ddc..84789a7a8e 100644--- a/libs/core/langchain_core/messages/block_translators/groq.py+++ b/libs/core/langchain_core/messages/block_translators/groq.py@@ -119,12 +119,26 @@ def _convert_to_v1_from_groq(message: AIMessage) -> list[types.ContentBlock]:def translate_content(message: AIMessage) -> list[types.ContentBlock]:- """Derive standard content blocks from a message with groq content."""+ """Derive standard content blocks from a message with groq content.++ Args:+ message: The message to translate.++ Returns:+ The derived content blocks.+ """return _convert_to_v1_from_groq(message)def translate_content_chunk(message: AIMessageChunk) -> list[types.ContentBlock]:- """Derive standard content blocks from a message chunk with groq content."""+ """Derive standard content blocks from a message chunk with groq content.++ Args:+ message: The message chunk to translate.++ Returns:+ The derived content blocks.+ """return _convert_to_v1_from_groq(message)diff --git a/libs/core/langchain_core/messages/block_translators/openai.py b/libs/core/langchain_core/messages/block_translators/openai.pyindex 1bc4b3f64f..875fee78ff 100644--- a/libs/core/langchain_core/messages/block_translators/openai.py+++ b/libs/core/langchain_core/messages/block_translators/openai.py@@ -19,7 +19,18 @@ if TYPE_CHECKING:def convert_to_openai_image_block(block: dict[str, Any]) -> dict:- """Convert `ImageContentBlock` to format expected by OpenAI Chat Completions."""+ """Convert `ImageContentBlock` to format expected by OpenAI Chat Completions.++ Args:+ block: The image content block to convert.++ Raises:+ ValueError: If required keys are missing.+ ValueError: If source type is unsupported.++ Returns:+ The formatted image content block.+ """if "url" in block:return {"type": "image_url",@@ -50,6 +61,18 @@ def convert_to_openai_data_block("Standard data content block" can include old-style LangChain v0 blocks(URLContentBlock, Base64ContentBlock, IDContentBlock) or new ones.++ Args:+ block: The content block to convert.+ api: The OpenAI API being targeted. Either "chat/completions" or "responses".++ Raises:+ ValueError: If required keys are missing.+ ValueError: If file URLs are used with Chat Completions API.+ ValueError: If block type is unsupported.++ Returns:+ The formatted content block."""if block["type"] == "image":chat_completions_block = convert_to_openai_image_block(block)@@ -981,7 +1004,14 @@ def _convert_to_v1_from_responses(message: AIMessage) -> list[types.ContentBlockdef translate_content(message: AIMessage) -> list[types.ContentBlock]:- """Derive standard content blocks from a message with OpenAI content."""+ """Derive standard content blocks from a message with OpenAI content.++ Args:+ message: The message to translate.++ Returns:+ The derived content blocks.+ """if isinstance(message.content, str):return _convert_to_v1_from_chat_completions(message)message = _convert_from_v03_ai_message(message)@@ -989,7 +1019,14 @@ def translate_content(message: AIMessage) -> list[types.ContentBlock]:def translate_content_chunk(message: AIMessageChunk) -> list[types.ContentBlock]:- """Derive standard content blocks from a message chunk with OpenAI content."""+ """Derive standard content blocks from a message chunk with OpenAI content.++ Args:+ message: The message chunk to translate.++ Returns:+ The derived content blocks.+ """if isinstance(message.content, str):return _convert_to_v1_from_chat_completions_chunk(message)message = _convert_from_v03_ai_message(message) # type: ignore[assignment]diff --git a/libs/core/langchain_core/output_parsers/openai_functions.py b/libs/core/langchain_core/output_parsers/openai_functions.pyindex 71e55d798d..9673ff77c9 100644--- a/libs/core/langchain_core/output_parsers/openai_functions.py+++ b/libs/core/langchain_core/output_parsers/openai_functions.py@@ -37,7 +37,7 @@ class OutputFunctionsParser(BaseGenerationOutputParser[Any]):The parsed JSON object.Raises:- `OutputParserException`: If the output is not valid JSON.+ OutputParserException: If the output is not valid JSON."""generation = result[0]if not isinstance(generation, ChatGeneration):@@ -88,7 +88,7 @@ class JsonOutputFunctionsParser(BaseCumulativeTransformOutputParser[Any]):The parsed JSON object.Raises:- OutputParserExcept`ion: If the output is not valid JSON.+ OutputParserException: If the output is not valid JSON."""if len(result) != 1:msg = f"Expected exactly one result, but got {len(result)}"diff --git a/libs/core/langchain_core/output_parsers/pydantic.py b/libs/core/langchain_core/output_parsers/pydantic.pyindex 9cfc14526a..cc3d186dbe 100644--- a/libs/core/langchain_core/output_parsers/pydantic.py+++ b/libs/core/langchain_core/output_parsers/pydantic.py@@ -54,7 +54,7 @@ class PydanticOutputParser(JsonOutputParser, Generic[TBaseModel]):all the keys that have been returned so far.Raises:- `OutputParserException`: If the result is not valid JSON+ OutputParserException: If the result is not valid JSONor does not conform to the Pydantic model.Returns:diff --git a/libs/core/langchain_core/prompts/structured.py b/libs/core/langchain_core/prompts/structured.pyindex 7e7dd73290..7adb673487 100644--- a/libs/core/langchain_core/prompts/structured.py+++ b/libs/core/langchain_core/prompts/structured.py@@ -48,6 +48,9 @@ class StructuredPrompt(ChatPromptTemplate):schema_: schema for the structured prompt.structured_output_kwargs: additional kwargs for structured output.template_format: template format for the prompt.++ Raises:+ ValueError: if schema is not provided."""schema_ = schema_ or kwargs.pop("schema", None)if not schema_:diff --git a/libs/core/langchain_core/runnables/graph_ascii.py b/libs/core/langchain_core/runnables/graph_ascii.pyindex 05692b857c..14d29a837d 100644--- a/libs/core/langchain_core/runnables/graph_ascii.py+++ b/libs/core/langchain_core/runnables/graph_ascii.py@@ -165,6 +165,9 @@ class AsciiCanvas:y0: y coordinate of the box corner.width: box width.height: box height.++ Raises:+ ValueError: if box dimensions are invalid."""if width <= 1 or height <= 1:msg = "Box dimensions should be > 1"diff --git a/libs/core/langchain_core/runnables/graph_mermaid.py b/libs/core/langchain_core/runnables/graph_mermaid.pyindex 25e961b924..5ce2378fff 100644--- a/libs/core/langchain_core/runnables/graph_mermaid.py+++ b/libs/core/langchain_core/runnables/graph_mermaid.py@@ -81,6 +81,7 @@ def draw_mermaid(}}```+Returns:Mermaid graph syntax.diff --git a/libs/core/langchain_core/tracers/event_stream.py b/libs/core/langchain_core/tracers/event_stream.pyindex 80ce1b7bf1..57bed0be53 100644--- a/libs/core/langchain_core/tracers/event_stream.py+++ b/libs/core/langchain_core/tracers/event_stream.py@@ -426,6 +426,10 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand"""Run on new output token. Only available when streaming is enabled.For both chat models and non-chat models (legacy LLMs).++ Raises:+ ValueError: If the run type is not `llm` or `chat_model`.+ AssertionError: If the run ID is not found in the run map."""run_info = self.run_map.get(run_id)chunk_: GenerationChunk | BaseMessageChunk@@ -707,11 +711,7 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand@overrideasync def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:- """End a trace for a tool run.-- Raises:- AssertionError: If the run ID is a tool call and does not have inputs- """+ """End a trace for a tool run."""run_info, inputs = self._get_tool_run_info_with_inputs(run_id)self._send(diff --git a/libs/core/langchain_core/utils/input.py b/libs/core/langchain_core/utils/input.pyindex d8946230bf..9a058a3604 100644--- a/libs/core/langchain_core/utils/input.py+++ b/libs/core/langchain_core/utils/input.py@@ -22,6 +22,9 @@ def get_color_mapping(Returns:The mapping of items to colors.++ Raises:+ ValueError: If no colors are available after applying exclusions."""colors = list(_TEXT_COLOR_MAPPING.keys())if excluded_colors is not None:diff --git a/libs/core/langchain_core/utils/uuid.py b/libs/core/langchain_core/utils/uuid.pyindex 32cf553b96..3d895edaba 100644--- a/libs/core/langchain_core/utils/uuid.py+++ b/libs/core/langchain_core/utils/uuid.py@@ -30,6 +30,9 @@ def uuid7(nanoseconds: int | None = None) -> UUID:Args:nanoseconds: Optional ns timestamp. If not provided, uses current time.++ Returns:+ A UUIDv7 object."""# --- 48 --- -- 4 -- --- 12 --- -- 2 -- --- 30 --- - 32 -# unix_ts_ms | version | counter_hi | variant | counter_lo | random