Update functions schema

Author: gopidesupavan

providers/common/ai/src/airflow/providers/common/ai/utils/function_schema.py

@@ -53,7 +53,8 @@
 )
 
 
-def _first_docstring_paragraph(obj: Any) -> str:
+def _extract_docstring_summary(obj: Any) -> str:
+    """Return leading descriptive docstring text before Args/Returns-style sections."""
     doc = inspect.getdoc(obj)
     if not doc:
         return ""
@@ -66,7 +67,7 @@ def _first_docstring_paragraph(obj: Any) -> str:
 
 
 def extract_function_description(fn: Callable[..., Any]) -> str:
-    """Return the first paragraph of *fn*'s docstring, stopping before Args/Returns sections."""
+    """Return a short description for *fn* from its leading docstring text."""
     # Unwrap partials to get the underlying function's docstring.
     if isinstance(fn, functools.partial):
         return extract_function_description(fn.func)
@@ -75,12 +76,12 @@ def extract_function_description(fn: Callable[..., Any]) -> str:
     # Prefer __call__ docstring (what calling does), then class docstring, then class name.
     if not hasattr(fn, "__name__"):
         return (
-            _first_docstring_paragraph(type(fn).__call__)
-            or _first_docstring_paragraph(fn)
+            _extract_docstring_summary(type(fn).__call__)
+            or _extract_docstring_summary(fn)
             or type(fn).__name__
         )
 
-    return _first_docstring_paragraph(fn) or fn.__name__
+    return _extract_docstring_summary(fn) or fn.__name__
 
 
 def build_function_json_schema(fn: Callable[..., Any]) -> dict[str, Any]:
@@ -92,11 +93,10 @@ def build_function_json_schema(fn: Callable[..., Any]) -> dict[str, Any]:
     Falls back to an empty object schema on any introspection failure.
 
     ``self``, ``cls``, ``*args``, and ``**kwargs`` are excluded.
+    Positional-only params are rejected because tool callables must accept
+    keyword arguments matching the generated schema.
     For ``functools.partial``, only the remaining free parameters appear.
     """
-    if inspect.isbuiltin(fn):
-        return _EMPTY_OBJECT_SCHEMA
-
     # Partials: sig from partial (bound args already removed), hints from inner fn.
     hint_source: Callable[..., Any] = fn
     if isinstance(fn, functools.partial):
@@ -118,6 +118,17 @@ def build_function_json_schema(fn: Callable[..., Any]) -> dict[str, Any]:
     for param_name, param in sig.parameters.items():
         if param_name in _SKIP_PARAMS:
             continue
+        if param.kind is inspect.Parameter.POSITIONAL_ONLY:
+            # Auto-generated tool schemas describe named JSON object fields,
+            # and tool frameworks invoke the callable with keyword arguments
+            # derived from those fields. A positional-only parameter cannot be
+            # satisfied by that contract, so fail fast with a clear error.
+            name = getattr(fn, "__name__", type(fn).__name__)
+            raise ValueError(
+                f"Cannot build a tool schema for {name}: "
+                f"parameter {param_name!r} is positional-only. "
+                "Tool parameters must be callable by keyword."
+            )
         if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
             continue
 

providers/common/ai/tests/unit/common/ai/utils/test_function_schema.py

@@ -17,6 +17,7 @@
 from __future__ import annotations
 
 import functools
+import inspect
 from typing import Annotated, Any
 
 import pytest
@@ -250,6 +251,12 @@ def fn(**kwargs: str): ...
         schema = build_function_json_schema(fn)
         assert "kwargs" not in schema.get("properties", {})
 
+    def test_positional_only_rejected(self):
+        def fn(x: int, /, y: str): ...
+
+        with pytest.raises(ValueError, match="parameter 'x' is positional-only"):
+            build_function_json_schema(fn)
+
     def test_unannotated_param_included_as_any(self):
         def fn(x): ...
 
@@ -301,9 +308,15 @@ def fn(x: int | None = None): ...
         assert "x" in schema["properties"]
         assert "x" not in schema.get("required", [])
 
-    def test_introspection_failure_returns_empty_schema(self):
-        # Built-in functions have no inspectable signature.
-        schema = build_function_json_schema(len)
+    def test_signature_failure_returns_empty_schema(self, monkeypatch):
+        def fn(x: int): ...
+
+        def raise_value_error(_):
+            raise ValueError("boom")
+
+        monkeypatch.setattr(inspect, "signature", raise_value_error)
+
+        schema = build_function_json_schema(fn)
         assert schema == _EMPTY_OBJECT_SCHEMA
 
     def test_callable_object_schema_from_call(self):