The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
docs(core): add docstrings to internal helper functions (#34525)
weiii6685517ef37fb30
diff --git a/libs/core/langchain_core/_api/__init__.py b/libs/core/langchain_core/_api/__init__.pyindex 54de1d18b7..12296ca363 100644--- a/libs/core/langchain_core/_api/__init__.py+++ b/libs/core/langchain_core/_api/__init__.py@@ -58,6 +58,20 @@ _dynamic_imports = {def __getattr__(attr_name: str) -> object:+ """Dynamically import and return an attribute from a submodule.++ This function enables lazy loading of API functions from submodules, reducing+ initial import time and circular dependency issues.++ Args:+ attr_name: Name of the attribute to import.++ Returns:+ The imported attribute object.++ Raises:+ AttributeError: If the attribute is not a valid dynamic import.+ """module_name = _dynamic_imports.get(attr_name)result = import_attr(attr_name, module_name, __spec__.parent)globals()[attr_name] = result@@ -65,4 +79,9 @@ def __getattr__(attr_name: str) -> object:def __dir__() -> list[str]:+ """Return a list of available attributes for this module.++ Returns:+ List of attribute names that can be imported from this module.+ """return list(__all__)diff --git a/libs/core/langchain_core/indexing/api.py b/libs/core/langchain_core/indexing/api.pyindex 65d0438163..da3c54fd63 100644--- a/libs/core/langchain_core/indexing/api.py+++ b/libs/core/langchain_core/indexing/api.py@@ -242,6 +242,17 @@ def _delete(vector_store: VectorStore | DocumentIndex,ids: list[str],) -> None:+ """Delete documents from a vector store or document index by their IDs.++ Args:+ vector_store: The vector store or document index to delete from.+ ids: List of document IDs to delete.++ Raises:+ IndexingException: If the delete operation fails.+ TypeError: If the `vector_store` is neither a `VectorStore` nor a+ `DocumentIndex`.+ """if isinstance(vector_store, VectorStore):delete_ok = vector_store.delete(ids)if delete_ok is not None and delete_ok is False:diff --git a/libs/core/langchain_core/utils/json.py b/libs/core/langchain_core/utils/json.pyindex 308c274045..14ff8a4239 100644--- a/libs/core/langchain_core/utils/json.py+++ b/libs/core/langchain_core/utils/json.py@@ -13,6 +13,14 @@ if TYPE_CHECKING:def _replace_new_line(match: re.Match[str]) -> str:+ """Replace newline characters in a regex match with escaped sequences.++ Args:+ match: Regex match object containing the string to process.++ Returns:+ String with newlines, carriage returns, tabs, and quotes properly escaped.+ """value = match.group(2)value = re.sub(r"\n", r"\\n", value)value = re.sub(r"\r", r"\\r", value)@@ -162,6 +170,20 @@ _json_strip_chars = " \n\r\t`"def _parse_json(json_str: str, *, parser: Callable[[str], Any] = parse_partial_json) -> Any:+ """Parse a JSON string, handling special characters and whitespace.++ Strips whitespace, newlines, and backticks from the start and end of the string,+ then processes special characters before parsing.++ Args:+ json_str: The JSON string to parse.+ parser: Optional custom parser function.++ Defaults to `parse_partial_json`.++ Returns:+ Parsed JSON object.+ """# Strip whitespace,newlines,backtick from the start and endjson_str = json_str.strip(_json_strip_chars)diff --git a/libs/core/langchain_core/utils/json_schema.py b/libs/core/langchain_core/utils/json_schema.pyindex 72f56fc2ef..11475accb0 100644--- a/libs/core/langchain_core/utils/json_schema.py+++ b/libs/core/langchain_core/utils/json_schema.py@@ -10,6 +10,22 @@ if TYPE_CHECKING:def _retrieve_ref(path: str, schema: dict) -> list | dict:+ """Retrieve a referenced object from a JSON schema using a path.++ Resolves JSON schema references (e.g., `'#/definitions/MyType'`) by traversing the+ schema structure.++ Args:+ path: Reference path starting with `'#'` (e.g., `'#/definitions/MyType'`).+ schema: The JSON schema dictionary to search in.++ Returns:+ A deep copy of the referenced object (dict or list).++ Raises:+ ValueError: If the path does not start with `'#'`.+ KeyError: If the reference path is not found in the schema.+ """components = path.split("/")if components[0] != "#":msg = (diff --git a/libs/core/langchain_core/utils/mustache.py b/libs/core/langchain_core/utils/mustache.pyindex 8134355a50..cce84753a2 100644--- a/libs/core/langchain_core/utils/mustache.py+++ b/libs/core/langchain_core/utils/mustache.py@@ -352,7 +352,26 @@ def _get_key(def_ldel: str,def_rdel: str,) -> Any:- """Return a key from the current scope."""+ """Retrieve a value from the current scope using a dot-separated key path.++ Traverses through nested dictionaries and lists using dot notation.++ Supports special key `'.'` to return the current scope.++ Args:+ key: Dot-separated key path (e.g., `'user.name'` or `'.'` for current scope).+ scopes: List of scope dictionaries to search through.+ warn: Whether to log a warning when a key is not found.+ keep: Whether to return the original template tag when key is not found.+ def_ldel: Left delimiter for template (used when keep is `True`).+ def_rdel: Right delimiter for template (used when keep is `True`).++ Returns:+ The value found at the key path.++ If not found, returns the original template tag when keep is `True`,+ otherwise returns an empty string.+ """# If the key is a dotif key == ".":# Then just return the current scopediff --git a/libs/core/langchain_core/utils/usage.py b/libs/core/langchain_core/utils/usage.pyindex b60b173cdf..47e483a555 100644--- a/libs/core/langchain_core/utils/usage.py+++ b/libs/core/langchain_core/utils/usage.py@@ -12,6 +12,27 @@ def _dict_int_op(depth: int = 0,max_depth: int = 100,) -> dict:+ """Apply an integer operation to corresponding values in two dictionaries.++ Recursively combines two dictionaries by applying the given operation to integer+ values at matching keys.++ Supports nested dictionaries.++ Args:+ left: First dictionary to combine.+ right: Second dictionary to combine.+ op: Binary operation function to apply to integer values.+ default: Default value to use when a key is missing from a dictionary.+ depth: Current recursion depth (used internally).+ max_depth: Maximum recursion depth (to prevent infinite loops).++ Returns:+ A new dictionary with combined values.++ Raises:+ ValueError: If `max_depth` is exceeded or if value types are not supported.+ """if depth >= max_depth:msg = f"{max_depth=} exceeded, unable to combine dicts."raise ValueError(msg)diff --git a/libs/core/langchain_core/vectorstores/__init__.py b/libs/core/langchain_core/vectorstores/__init__.pyindex 560a0d1678..1da27459d6 100644--- a/libs/core/langchain_core/vectorstores/__init__.py+++ b/libs/core/langchain_core/vectorstores/__init__.py@@ -24,6 +24,20 @@ _dynamic_imports = {def __getattr__(attr_name: str) -> object:+ """Dynamically import and return an attribute from a submodule.++ This function enables lazy loading of vectorstore classes from submodules, reducing+ initial import time and circular dependency issues.++ Args:+ attr_name: Name of the attribute to import.++ Returns:+ The imported attribute object.++ Raises:+ AttributeError: If the attribute is not found in `_dynamic_imports`.+ """module_name = _dynamic_imports.get(attr_name)result = import_attr(attr_name, module_name, __spec__.parent)globals()[attr_name] = result@@ -31,4 +45,9 @@ def __getattr__(attr_name: str) -> object:def __dir__() -> list[str]:+ """Return a list of available attributes for this module.++ Returns:+ List of attribute names that can be imported from this module.+ """return list(__all__)