Skip to content

The agent engineering platform.

docs(core): update docstrings in `RunnableConfig`, `dereference_refs` (#34131)

Mason Daugherty12df938ace9d
diff --git a/libs/core/langchain_core/runnables/config.py b/libs/core/langchain_core/runnables/config.py
index f67bf09592..3f165d71d4 100644
--- a/libs/core/langchain_core/runnables/config.py
+++ b/libs/core/langchain_core/runnables/config.py
@@ -47,54 +47,59 @@ class EmptyDict(TypedDict, total=False):
class RunnableConfig(TypedDict, total=False):
- """Configuration for a Runnable."""
+ """Configuration for a `Runnable`.
- tags: list[str]
+ See the [reference docs](https://reference.langchain.com/python/langchain_core/runnables/#langchain_core.runnables.RunnableConfig)
+ for more details.
"""
- Tags for this call and any sub-calls (eg. a Chain calling an LLM).
+
+ tags: list[str]
+ """Tags for this call and any sub-calls (e.g. a Chain calling an LLM).
+
You can use these to filter calls.
"""
metadata: dict[str, Any]
- """
- Metadata for this call and any sub-calls (eg. a Chain calling an LLM).
+ """Metadata for this call and any sub-calls (e.g. a Chain calling an LLM).
+
Keys should be strings, values should be JSON-serializable.
"""
callbacks: Callbacks
- """
- Callbacks for this call and any sub-calls (eg. a Chain calling an LLM).
+ """Callbacks for this call and any sub-calls (e.g. a Chain calling an LLM).
+
Tags are passed to all callbacks, metadata is passed to handle*Start callbacks.
"""
run_name: str
- """
- Name for the tracer run for this call. Defaults to the name of the class.
- """
+ """Name for the tracer run for this call.
+
+ Defaults to the name of the class."""
max_concurrency: int | None
- """
- Maximum number of parallel calls to make. If not provided, defaults to
- `ThreadPoolExecutor`'s default.
+ """Maximum number of parallel calls to make.
+
+ If not provided, defaults to `ThreadPoolExecutor`'s default.
"""
recursion_limit: int
- """
- Maximum number of times a call can recurse. If not provided, defaults to `25`.
+ """Maximum number of times a call can recurse.
+
+ If not provided, defaults to `25`.
"""
configurable: dict[str, Any]
- """
- Runtime values for attributes previously made configurable on this `Runnable`,
+ """Runtime values for attributes previously made configurable on this `Runnable`,
or sub-Runnables, through `configurable_fields` or `configurable_alternatives`.
+
Check `output_schema` for a description of the attributes that have been made
configurable.
"""
run_id: uuid.UUID | None
- """
- Unique identifier for the tracer run for this call. If not provided, a new UUID
- will be generated.
+ """Unique identifier for the tracer run for this call.
+
+ If not provided, a new UUID will be generated.
"""
diff --git a/libs/core/langchain_core/utils/json_schema.py b/libs/core/langchain_core/utils/json_schema.py
index 68b04beb8c..1874e45aec 100644
--- a/libs/core/langchain_core/utils/json_schema.py
+++ b/libs/core/langchain_core/utils/json_schema.py
@@ -170,28 +170,33 @@ def dereference_refs(
full_schema: dict | None = None,
skip_keys: Sequence[str] | None = None,
) -> dict:
- """Resolve and inline JSON Schema $ref references in a schema object.
+ """Resolve and inline JSON Schema `$ref` references in a schema object.
- This function processes a JSON Schema and resolves all $ref references by replacing
- them with the actual referenced content. It handles both simple references and
- complex cases like circular references and mixed $ref objects that contain
- additional properties alongside the $ref.
+ This function processes a JSON Schema and resolves all `$ref` references by
+ replacing them with the actual referenced content.
+
+ Handles both simple references and complex cases like circular references and mixed
+ `$ref` objects that contain additional properties alongside the `$ref`.
Args:
- schema_obj: The JSON Schema object or fragment to process. This can be a
- complete schema or just a portion of one.
- full_schema: The complete schema containing all definitions that $refs might
- point to. If not provided, defaults to schema_obj (useful when the
- schema is self-contained).
- skip_keys: Controls recursion behavior and reference resolution depth:
- - If `None` (Default): Only recurse under '$defs' and use shallow reference
- resolution (break cycles but don't deep-inline nested refs)
- - If provided (even as []): Recurse under all keys and use deep reference
- resolution (fully inline all nested references)
+ schema_obj: The JSON Schema object or fragment to process.
+
+ This can be a complete schema or just a portion of one.
+ full_schema: The complete schema containing all definitions that `$refs` might
+ point to.
+
+ If not provided, defaults to `schema_obj` (useful when the schema is
+ self-contained).
+ skip_keys: Controls recursion behavior and reference resolution depth.
+
+ - If `None` (Default): Only recurse under `'$defs'` and use shallow
+ reference resolution (break cycles but don't deep-inline nested refs)
+ - If provided (even as `[]`): Recurse under all keys and use deep reference
+ resolution (fully inline all nested references)
Returns:
- A new dictionary with all $ref references resolved and inlined. The original
- schema_obj is not modified.
+ A new dictionary with all $ref references resolved and inlined.
+ The original `schema_obj` is not modified.
Examples:
Basic reference resolution:
@@ -203,7 +208,8 @@ def dereference_refs(
>>> result = dereference_refs(schema)
>>> result["properties"]["name"] # {"type": "string"}
- Mixed $ref with additional properties:
+ Mixed `$ref` with additional properties:
+
>>> schema = {
... "properties": {
... "name": {"$ref": "#/$defs/base", "description": "User name"}
@@ -215,6 +221,7 @@ def dereference_refs(
# {"type": "string", "minLength": 1, "description": "User name"}
Handling circular references:
+
>>> schema = {
... "properties": {"user": {"$ref": "#/$defs/User"}},
... "$defs": {
@@ -227,10 +234,11 @@ def dereference_refs(
>>> result = dereference_refs(schema) # Won't cause infinite recursion
!!! note
+
- Circular references are handled gracefully by breaking cycles
- - Mixed $ref objects (with both $ref and other properties) are supported
- - Additional properties in mixed $refs override resolved properties
- - The $defs section is preserved in the output by default
+ - Mixed `$ref` objects (with both `$ref` and other properties) are supported
+ - Additional properties in mixed `$refs` override resolved properties
+ - The `$defs` section is preserved in the output by default
"""
full = full_schema or schema_obj
keys_to_skip = list(skip_keys) if skip_keys is not None else ["$defs"]