The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
[Core] Unify function schema parsing (#23370)
William FH6cd56821dc0e
diff --git a/libs/core/langchain_core/tools.py b/libs/core/langchain_core/tools.pyindex cf168e784b..90212af424 100644--- a/libs/core/langchain_core/tools.py+++ b/libs/core/langchain_core/tools.py@@ -28,7 +28,20 @@ from abc import ABC, abstractmethodfrom contextvars import copy_contextfrom functools import partialfrom inspect import signature-from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple, Type, Union+from typing import (+ Any,+ Awaitable,+ Callable,+ Dict,+ List,+ Optional,+ Sequence,+ Tuple,+ Type,+ Union,+)++from typing_extensions import Annotated, get_args, get_originfrom langchain_core._api import deprecatedfrom langchain_core.callbacks import (@@ -76,11 +89,32 @@ class SchemaAnnotationError(TypeError):"""Raised when 'args_schema' is missing or has an incorrect type annotation."""+def _is_annotated_type(typ: Type[Any]) -> bool:+ return get_origin(typ) is Annotated+++def _get_annotation_description(arg: str, arg_type: Type[Any]) -> str | None:+ if _is_annotated_type(arg_type):+ annotated_args = get_args(arg_type)+ arg_type = annotated_args[0]+ if len(annotated_args) > 1:+ for annotation in annotated_args[1:]:+ if isinstance(annotation, str):+ return annotation+ return None++def _create_subset_model(- name: str, model: Type[BaseModel], field_names: list+ name: str,+ model: Type[BaseModel],+ field_names: list,+ *,+ descriptions: Optional[dict] = None,+ fn_description: Optional[str] = None,) -> Type[BaseModel]:"""Create a pydantic model with only a subset of model's fields."""fields = {}+for field_name in field_names:field = model.__fields__[field_name]t = (@@ -89,19 +123,89 @@ def _create_subset_model(if field.required and not field.allow_noneelse Optional[field.outer_type_])+ if descriptions and field_name in descriptions:+ field.field_info.description = descriptions[field_name]fields[field_name] = (t, field.field_info)+rtn = create_model(name, **fields) # type: ignore+ rtn.__doc__ = textwrap.dedent(fn_description or model.__doc__ or "")return rtndef _get_filtered_args(inferred_model: Type[BaseModel],func: Callable,+ *,+ filter_args: Sequence[str],) -> dict:"""Get the arguments from a function's signature."""schema = inferred_model.schema()["properties"]valid_keys = signature(func).parameters- return {k: schema[k] for k in valid_keys if k not in ("run_manager", "callbacks")}+ return {+ k: schema[k]+ for i, (k, param) in enumerate(valid_keys.items())+ if k not in filter_args and (i > 0 or param.name not in ("self", "cls"))+ }+++def _parse_python_function_docstring(function: Callable) -> Tuple[str, dict]:+ """Parse the function and argument descriptions from the docstring of a function.++ Assumes the function docstring follows Google Python style guide.+ """+ docstring = inspect.getdoc(function)+ if docstring:+ docstring_blocks = docstring.split("\n\n")+ descriptors = []+ args_block = None+ past_descriptors = False+ for block in docstring_blocks:+ if block.startswith("Args:"):+ args_block = block+ break+ elif block.startswith("Returns:") or block.startswith("Example:"):+ # Don't break in case Args come after+ past_descriptors = True+ elif not past_descriptors:+ descriptors.append(block)+ else:+ continue+ description = " ".join(descriptors)+ else:+ description = ""+ args_block = None+ arg_descriptions = {}+ if args_block:+ arg = None+ for line in args_block.split("\n")[1:]:+ if ":" in line:+ arg, desc = line.split(":", maxsplit=1)+ arg_descriptions[arg.strip()] = desc.strip()+ elif arg:+ arg_descriptions[arg.strip()] += " " + line.strip()+ return description, arg_descriptions+++def _infer_arg_descriptions(+ fn: Callable, *, parse_docstring: bool = False+) -> Tuple[str, dict]:+ """Infer argument descriptions from a function's docstring."""+ if parse_docstring:+ description, arg_descriptions = _parse_python_function_docstring(fn)+ else:+ description = inspect.getdoc(fn) or ""+ arg_descriptions = {}+ if hasattr(inspect, "get_annotations"):+ # This is for python < 3.10+ annotations = inspect.get_annotations(fn) # type: ignore+ else:+ annotations = getattr(fn, "__annotations__", {})+ for arg, arg_type in annotations.items():+ if arg in arg_descriptions:+ continue+ if desc := _get_annotation_description(arg, arg_type):+ arg_descriptions[arg] = desc+ return description, arg_descriptionsclass _SchemaConfig:@@ -114,25 +218,40 @@ class _SchemaConfig:def create_schema_from_function(model_name: str,func: Callable,+ *,+ filter_args: Optional[Sequence[str]] = None,+ parse_docstring: bool = False,) -> Type[BaseModel]:"""Create a pydantic schema from a function's signature.Args:model_name: Name to assign to the generated pydandic schemafunc: Function to generate the schema from+ filter_args: Optional list of arguments to exclude from the schema+ parse_docstring: Whether to parse the function's docstring for descriptions+ for each argument.Returns:A pydantic model with the same arguments as the function"""# https://docs.pydantic.dev/latest/usage/validation_decorator/validated = validate_arguments(func, config=_SchemaConfig) # type: ignoreinferred_model = validated.model # type: ignore- if "run_manager" in inferred_model.__fields__:- del inferred_model.__fields__["run_manager"]- if "callbacks" in inferred_model.__fields__:- del inferred_model.__fields__["callbacks"]+ filter_args = (+ filter_args if filter_args is not None else ("run_manager", "callbacks")+ )+ for arg in filter_args:+ if arg in inferred_model.__fields__:+ del inferred_model.__fields__[arg]+ description, arg_descriptions = _infer_arg_descriptions(+ func, parse_docstring=parse_docstring+ )# Pydantic adds placeholder virtual fields we need to strip- valid_properties = _get_filtered_args(inferred_model, func)+ valid_properties = _get_filtered_args(inferred_model, func, filter_args=filter_args)return _create_subset_model(- f"{model_name}Schema", inferred_model, list(valid_properties)+ f"{model_name}Schema",+ inferred_model,+ list(valid_properties),+ descriptions=arg_descriptions,+ fn_description=description,)diff --git a/libs/core/langchain_core/utils/function_calling.py b/libs/core/langchain_core/utils/function_calling.pyindex e8b1e32d1c..f4bcba6e70 100644--- a/libs/core/langchain_core/utils/function_calling.py+++ b/libs/core/langchain_core/utils/function_calling.py@@ -2,10 +2,8 @@from __future__ import annotations-import inspectimport loggingimport uuid-from types import FunctionType, MethodTypefrom typing import (TYPE_CHECKING,Any,@@ -14,13 +12,12 @@ from typing import (List,Literal,Optional,- Tuple,Type,Union,cast,)-from typing_extensions import Annotated, TypedDict, get_args, get_origin+from typing_extensions import TypedDictfrom langchain_core._api import deprecatedfrom langchain_core.messages import (@@ -123,122 +120,6 @@ def _get_python_function_name(function: Callable) -> str:return function.__name__-def _parse_python_function_docstring(function: Callable) -> Tuple[str, dict]:- """Parse the function and argument descriptions from the docstring of a function.-- Assumes the function docstring follows Google Python style guide.- """- docstring = inspect.getdoc(function)- if docstring:- docstring_blocks = docstring.split("\n\n")- descriptors = []- args_block = None- past_descriptors = False- for block in docstring_blocks:- if block.startswith("Args:"):- args_block = block- break- elif block.startswith("Returns:") or block.startswith("Example:"):- # Don't break in case Args come after- past_descriptors = True- elif not past_descriptors:- descriptors.append(block)- else:- continue- description = " ".join(descriptors)- else:- description = ""- args_block = None- arg_descriptions = {}- if args_block:- arg = None- for line in args_block.split("\n")[1:]:- if ":" in line:- arg, desc = line.split(":", maxsplit=1)- arg_descriptions[arg.strip()] = desc.strip()- elif arg:- arg_descriptions[arg.strip()] += " " + line.strip()- return description, arg_descriptions---def _is_annotated_type(typ: Type[Any]) -> bool:- return get_origin(typ) is Annotated---def _get_python_function_arguments(function: Callable, arg_descriptions: dict) -> dict:- """Get JsonSchema describing a Python functions arguments.-- Assumes all function arguments are of primitive types (int, float, str, bool) or- are subclasses of pydantic.BaseModel.- """- properties = {}- annotations = inspect.getfullargspec(function).annotations- for arg, arg_type in annotations.items():- if arg == "return":- continue-- if _is_annotated_type(arg_type):- annotated_args = get_args(arg_type)- arg_type = annotated_args[0]- if len(annotated_args) > 1:- for annotation in annotated_args[1:]:- if isinstance(annotation, str):- arg_descriptions[arg] = annotation- break- if (- isinstance(arg_type, type)- and hasattr(arg_type, "model_json_schema")- and callable(arg_type.model_json_schema)- ):- properties[arg] = arg_type.model_json_schema()- elif (- isinstance(arg_type, type)- and hasattr(arg_type, "schema")- and callable(arg_type.schema)- ):- properties[arg] = arg_type.schema()- elif (- hasattr(arg_type, "__name__")- and getattr(arg_type, "__name__") in PYTHON_TO_JSON_TYPES- ):- properties[arg] = {"type": PYTHON_TO_JSON_TYPES[arg_type.__name__]}- elif (- hasattr(arg_type, "__dict__")- and getattr(arg_type, "__dict__").get("__origin__", None) == Literal- ):- properties[arg] = {- "enum": list(arg_type.__args__),- "type": PYTHON_TO_JSON_TYPES[arg_type.__args__[0].__class__.__name__],- }- else:- logger.warning(- f"Argument {arg} of type {arg_type} from function {function.__name__} "- "could not be not be converted to a JSON schema."- )-- if arg in arg_descriptions:- if arg not in properties:- properties[arg] = {}- properties[arg]["description"] = arg_descriptions[arg]-- return properties---def _get_python_function_required_args(function: Callable) -> List[str]:- """Get the required arguments for a Python function."""- spec = inspect.getfullargspec(function)- required = spec.args[: -len(spec.defaults)] if spec.defaults else spec.args- required += [k for k in spec.kwonlyargs if k not in (spec.kwonlydefaults or {})]-- is_function_type = isinstance(function, FunctionType)- is_method_type = isinstance(function, MethodType)- if required and is_function_type and required[0] == "self":- required = required[1:]- elif required and is_method_type and required[0] == "cls":- required = required[1:]- return required--@deprecated("0.1.16",alternative="langchain_core.utils.function_calling.convert_to_openai_function()",@@ -246,23 +127,24 @@ def _get_python_function_required_args(function: Callable) -> List[str]:)def convert_python_function_to_openai_function(function: Callable,-) -> Dict[str, Any]:+) -> FunctionDescription:"""Convert a Python function to an OpenAI function-calling API compatible dict.Assumes the Python function has type hints and a docstring with a description. Ifthe docstring has Google Python style argument descriptions, these will beincluded as well."""- description, arg_descriptions = _parse_python_function_docstring(function)- return {- "name": _get_python_function_name(function),- "description": description,- "parameters": {- "type": "object",- "properties": _get_python_function_arguments(function, arg_descriptions),- "required": _get_python_function_required_args(function),- },- }+ from langchain_core import tools++ func_name = _get_python_function_name(function)+ model = tools.create_schema_from_function(+ func_name, function, filter_args=(), parse_docstring=True+ )+ return convert_pydantic_to_openai_function(+ model,+ name=func_name,+ description=model.__doc__,+ )@deprecated(@@ -343,7 +225,7 @@ def convert_to_openai_function(elif isinstance(function, BaseTool):return cast(Dict, format_tool_to_openai_function(function))elif callable(function):- return convert_python_function_to_openai_function(function)+ return cast(Dict, convert_python_function_to_openai_function(function))else:raise ValueError(f"Unsupported function\n\n{function}\n\nFunctions must be passed in"diff --git a/libs/core/tests/unit_tests/test_tools.py b/libs/core/tests/unit_tests/test_tools.pyindex 5e7b05dbff..968b2a03d4 100644--- a/libs/core/tests/unit_tests/test_tools.py+++ b/libs/core/tests/unit_tests/test_tools.py@@ -1,6 +1,7 @@"""Test the base tool implementation."""import asyncio+import inspectimport jsonimport sysimport textwrap@@ -10,6 +11,7 @@ from functools import partialfrom typing import Any, Callable, Dict, List, Optional, Type, Unionimport pytest+from typing_extensions import Annotatedfrom langchain_core.callbacks import (AsyncCallbackManagerForToolRun,@@ -310,9 +312,10 @@ def test_structured_tool_from_function_docstring() -> None:def foo(bar: int, baz: str) -> str:"""Docstring+Args:- bar: int- baz: str+ bar: the bar value+ baz: the baz value"""raise NotImplementedError()@@ -328,6 +331,7 @@ def test_structured_tool_from_function_docstring() -> None:"bar": {"title": "Bar", "type": "integer"},"baz": {"title": "Baz", "type": "string"},},+ "description": inspect.getdoc(foo),"title": "fooSchema","type": "object","required": ["bar", "baz"],@@ -342,6 +346,7 @@ def test_structured_tool_from_function_docstring_complex_args() -> None:def foo(bar: int, baz: List[str]) -> str:"""Docstring+Args:bar: intbaz: List[str]@@ -352,14 +357,23 @@ def test_structured_tool_from_function_docstring_complex_args() -> None:assert structured_tool.name == "foo"assert structured_tool.args == {"bar": {"title": "Bar", "type": "integer"},- "baz": {"title": "Baz", "type": "array", "items": {"type": "string"}},+ "baz": {+ "title": "Baz",+ "type": "array",+ "items": {"type": "string"},+ },}assert structured_tool.args_schema.schema() == {"properties": {"bar": {"title": "Bar", "type": "integer"},- "baz": {"title": "Baz", "type": "array", "items": {"type": "string"}},+ "baz": {+ "title": "Baz",+ "type": "array",+ "items": {"type": "string"},+ },},+ "description": inspect.getdoc(foo),"title": "fooSchema","type": "object","required": ["bar", "baz"],@@ -439,6 +453,7 @@ def test_structured_tool_from_function_with_run_manager() -> None:bar: int, baz: str, callbacks: Optional[CallbackManagerForToolRun] = None) -> str:"""Docstring+Args:bar: intbaz: str@@ -459,6 +474,7 @@ def test_structured_tool_from_function_with_run_manager() -> None:"bar": {"title": "Bar", "type": "integer"},"baz": {"title": "Baz", "type": "string"},},+ "description": inspect.getdoc(foo),"title": "fooSchema","type": "object","required": ["bar", "baz"],@@ -675,10 +691,11 @@ def test_structured_tool_from_function() -> None:"""Test that structured tools can be created from functions."""def foo(bar: int, baz: str) -> str:- """Docstring+ """Docstring thing.+Args:- bar: int- baz: str+ bar: the bar value+ baz: the baz value"""raise NotImplementedError()@@ -692,6 +709,7 @@ def test_structured_tool_from_function() -> None:assert structured_tool.args_schema.schema() == {"title": "fooSchema","type": "object",+ "description": inspect.getdoc(foo),"properties": {"bar": {"title": "Bar", "type": "integer"},"baz": {"title": "Baz", "type": "string"},@@ -916,3 +934,56 @@ def test_tool_description() -> None:foo2 = StructuredTool.from_function(foo)assert foo2.description == "The foo."+++def test_tool_arg_descriptions() -> None:+ def foo(bar: str, baz: int) -> str:+ """The foo.++ Args:+ bar: The bar.+ baz: The baz.+ """+ return bar++ foo1 = tool(foo)+ args_schema = foo1.args_schema.schema() # type: ignore+ assert args_schema == {+ "title": "fooSchema",+ "type": "object",+ "description": inspect.getdoc(foo),+ "properties": {+ "bar": {"title": "Bar", "type": "string"},+ "baz": {"title": "Baz", "type": "integer"},+ },+ "required": ["bar", "baz"],+ }+++def test_tool_annotated_descriptions() -> None:+ def foo(+ bar: Annotated[str, "this is the bar"], baz: Annotated[int, "this is the baz"]+ ) -> str:+ """The foo.++ Returns:+ The bar only.+ """+ return bar++ foo1 = tool(foo)+ args_schema = foo1.args_schema.schema() # type: ignore+ assert args_schema == {+ "title": "fooSchema",+ "type": "object",+ "description": inspect.getdoc(foo),+ "properties": {+ "bar": {"title": "Bar", "type": "string", "description": "this is the bar"},+ "baz": {+ "title": "Baz",+ "type": "integer",+ "description": "this is the baz",+ },+ },+ "required": ["bar", "baz"],+ }diff --git a/libs/core/tests/unit_tests/utils/test_function_calling.py b/libs/core/tests/unit_tests/utils/test_function_calling.pyindex ddf19e87e9..6702b5ad63 100644--- a/libs/core/tests/unit_tests/utils/test_function_calling.py+++ b/libs/core/tests/unit_tests/utils/test_function_calling.py@@ -252,7 +252,7 @@ def test_function_no_params() -> None:passfunc = convert_to_openai_function(nullary_function)- req = func["parameters"]["required"]+ req = func["parameters"].get("required")assert not req