Skip to content

The agent engineering platform.

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.py
index 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.ContentBlock
def 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.py
index 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 parsing
return _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.py
index 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.py
index 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.py
index 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.py
index 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.ContentBlock
def 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.py
index 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.py
index 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 JSON
or 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.py
index 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.py
index 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.py
index 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.py
index 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
@override
async 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.py
index 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.py
index 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