|
| 1 | +# Copyright 2024 Google LLC |
| 2 | +# |
| 3 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +# you may not use this file except in compliance with the License. |
| 5 | +# You may obtain a copy of the License at |
| 6 | +# |
| 7 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +# |
| 9 | +# Unless required by applicable law or agreed to in writing, software |
| 10 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +# See the License for the specific language governing permissions and |
| 13 | +# limitations under the License. |
| 14 | +# |
| 15 | +"""Shared utilities for working with function schemas.""" |
| 16 | + |
| 17 | +import inspect |
| 18 | +import typing |
| 19 | +from typing import Any, Callable, Dict |
| 20 | +import warnings |
| 21 | + |
| 22 | +from google.cloud.aiplatform_v1beta1 import types as aiplatform_types |
| 23 | + |
| 24 | +Struct = Dict[str, Any] |
| 25 | + |
| 26 | + |
| 27 | +def _generate_json_schema_from_function_using_pydantic( |
| 28 | + func: Callable, |
| 29 | +) -> Struct: |
| 30 | + """Generates JSON Schema for a callable object. |
| 31 | +
|
| 32 | + The `func` function needs to follow specific rules. |
| 33 | + All parameters must be names explicitly (`*args` and `**kwargs` are not supported). |
| 34 | +
|
| 35 | + Args: |
| 36 | + func: Function for which to generate schema |
| 37 | +
|
| 38 | + Returns: |
| 39 | + The JSON Schema for the function as a dict. |
| 40 | + """ |
| 41 | + import pydantic |
| 42 | + |
| 43 | + try: |
| 44 | + import docstring_parser # pylint: disable=g-import-not-at-top |
| 45 | + except ImportError: |
| 46 | + warnings.warn("Unable to import docstring_parser") |
| 47 | + docstring_parser = None |
| 48 | + |
| 49 | + function_description = func.__doc__ |
| 50 | + |
| 51 | + # Parse parameter descriptions from the docstring. |
| 52 | + # Also parse the function descripton in a better way. |
| 53 | + parameter_descriptions = {} |
| 54 | + if docstring_parser: |
| 55 | + parsed_docstring = docstring_parser.parse(func.__doc__) |
| 56 | + function_description = ( |
| 57 | + parsed_docstring.long_description or parsed_docstring.short_description |
| 58 | + ) |
| 59 | + for meta in parsed_docstring.meta: |
| 60 | + if isinstance(meta, docstring_parser.DocstringParam): |
| 61 | + parameter_descriptions[meta.arg_name] = meta.description |
| 62 | + |
| 63 | + defaults = dict(inspect.signature(func).parameters) |
| 64 | + fields_dict = { |
| 65 | + name: ( |
| 66 | + # 1. We infer the argument type here: use Any rather than None so |
| 67 | + # it will not try to auto-infer the type based on the default value. |
| 68 | + ( |
| 69 | + param.annotation if param.annotation != inspect.Parameter.empty |
| 70 | + else Any |
| 71 | + ), |
| 72 | + pydantic.Field( |
| 73 | + # 2. We do not support default values for now. |
| 74 | + default=( |
| 75 | + param.default if param.default != inspect.Parameter.empty |
| 76 | + # ! Need to use pydantic.Undefined instead of None |
| 77 | + else pydantic.fields.Undefined |
| 78 | + ), |
| 79 | + # 3. We support user-provided descriptions. |
| 80 | + description=parameter_descriptions.get(name, None), |
| 81 | + ) |
| 82 | + ) |
| 83 | + for name, param in defaults.items() |
| 84 | + # We do not support *args or **kwargs |
| 85 | + if param.kind in ( |
| 86 | + inspect.Parameter.POSITIONAL_OR_KEYWORD, |
| 87 | + inspect.Parameter.KEYWORD_ONLY, |
| 88 | + inspect.Parameter.POSITIONAL_ONLY, |
| 89 | + ) |
| 90 | + } |
| 91 | + function_schema = pydantic.create_model(func.__name__, **fields_dict).schema() |
| 92 | + |
| 93 | + function_schema["title"] = func.__name__ |
| 94 | + function_schema["description"] = function_description |
| 95 | + # Postprocessing |
| 96 | + for name, property_schema in function_schema.get("properties", {}).items(): |
| 97 | + annotation = defaults[name].annotation |
| 98 | + # 5. Nullable fields: |
| 99 | + # * https://github.com/pydantic/pydantic/issues/1270 |
| 100 | + # * https://stackoverflow.com/a/58841311 |
| 101 | + # * https://github.com/pydantic/pydantic/discussions/4872 |
| 102 | + if ( |
| 103 | + typing.get_origin(annotation) is typing.Union |
| 104 | + and type(None) in typing.get_args(annotation) |
| 105 | + ): |
| 106 | + # for "typing.Optional" arguments, function_arg might be a |
| 107 | + # dictionary like |
| 108 | + # |
| 109 | + # {'anyOf': [{'type': 'integer'}, {'type': 'null'}] |
| 110 | + for schema in property_schema.pop("anyOf", []): |
| 111 | + schema_type = schema.get("type") |
| 112 | + if schema_type and schema_type != "null": |
| 113 | + property_schema["type"] = schema_type |
| 114 | + break |
| 115 | + property_schema["nullable"] = True |
| 116 | + # 6. Annotate required fields. |
| 117 | + function_schema["required"] = [ |
| 118 | + k for k in defaults if ( |
| 119 | + defaults[k].default == inspect.Parameter.empty |
| 120 | + and defaults[k].kind in ( |
| 121 | + inspect.Parameter.POSITIONAL_OR_KEYWORD, |
| 122 | + inspect.Parameter.KEYWORD_ONLY, |
| 123 | + inspect.Parameter.POSITIONAL_ONLY, |
| 124 | + ) |
| 125 | + ) |
| 126 | + ] |
| 127 | + return function_schema |
| 128 | + |
| 129 | + |
| 130 | +def adapt_json_schema_to_google_tool_schema(schema: Struct) -> Struct: |
| 131 | + """Adapts JSON schema to Google tool schema.""" |
| 132 | + fixed_schema = dict(schema) |
| 133 | + # `$schema` is one of the basic/most common fields of the real JSON Schema. |
| 134 | + # But Google's Schema proto does not support it. |
| 135 | + # Common attributes that we remove: |
| 136 | + # $schema, additionalProperties |
| 137 | + for key in list(fixed_schema): |
| 138 | + if not hasattr(aiplatform_types.Schema, key) and not hasattr( |
| 139 | + aiplatform_types.Schema, key + "_" |
| 140 | + ): |
| 141 | + fixed_schema.pop(key, None) |
| 142 | + property_schemas = fixed_schema.get("properties") |
| 143 | + if property_schemas: |
| 144 | + for k, v in property_schemas.items(): |
| 145 | + property_schemas[k] = adapt_json_schema_to_google_tool_schema(v) |
| 146 | + return fixed_schema |
| 147 | + |
| 148 | + |
| 149 | +generate_json_schema_from_function = _generate_json_schema_from_function_using_pydantic |
0 commit comments