Convert all legacy scalar examples to new Param API with type_bound support

- Add type_bound validation to _validate_param_types for AnyArrow params
- Convert DoubleColumnFunction to use Param(AnyArrow, type_bound=...)
- Convert AddNumericColumnsFunction to use Param(AnyArrow, type_bound=...)
- Convert SumColumnsFunction to use Param(AnyArrow, type_bound=..., varargs=True)
- Fix type_bound warning check to also consider is_any flag for new API
- Update module docstring to reflect all functions using new API

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rustyconover

vgi/arguments.py

@@ -719,7 +719,8 @@ def __call__(
                 )
 
         # Warn if type_bound is used with non-AnyArrow type
-        if type_bound is not None and self._type_param is not AnyArrow:
+        # Check both _type_param (legacy API) and is_any (new Param API)
+        if type_bound is not None and self._type_param is not AnyArrow and not is_any:
             type_name = getattr(self._type_param, "__name__", str(self._type_param))
             warnings.warn(
                 f"type_bound is only meaningful for Arg[AnyArrow], "

vgi/examples/scalar.py

@@ -3,28 +3,30 @@
 This module provides example scalar functions that transform input batches
 to single-column output with 1:1 row mapping.
 
-NEW PARAM/CONSTPARAM/RETURNS API
---------------------------------
+All functions use the Param/ConstParam/Returns API:
+
+STATIC OUTPUT TYPE
+------------------
 MultiplyFunction            - Multiplies column by constant (ConstParam example)
 UpperCaseFunction           - Converts string column to uppercase
 NullHandlingFunction        - Demonstrates special null handling (NullHandling.SPECIAL)
 RandomIntFunction           - Generates random integers (VOLATILE stability)
 
-LEGACY ARG DESCRIPTOR API (still supported)
--------------------------------------------
+DYNAMIC OUTPUT TYPE (with type_bound)
+-------------------------------------
 DoubleColumnFunction        - Doubles values in a numeric column (AnyArrow + type_bound)
 AddNumericColumnsFunction   - Adds two numeric columns (type promotion)
 SumColumnsFunction          - Sums multiple columns (varargs example)
 """
 
 from __future__ import annotations
 
-from typing import Annotated, Any
+from typing import Any
 
 import pyarrow as pa
 import pyarrow.compute as pc
 
-from vgi.arguments import AnyArrow, AnyArrowValue, Arg, ConstParam, Param, Returns
+from vgi.arguments import AnyArrow, ConstParam, Param, Returns
 from vgi.exceptions import SchemaValidationError
 from vgi.metadata import FunctionExample, FunctionStability, NullHandling
 from vgi.scalar_function import ScalarFunction
@@ -125,17 +127,16 @@ def compute(
         return pc.multiply(column, factor)
 
 
-# =============================================================================
-# Legacy Arg Descriptor API Examples (still supported)
-# =============================================================================
-
-
 class DoubleColumnFunction(ScalarFunction):
     """Doubles values in a numeric column.
 
+    This example demonstrates the new Param API with:
+    - AnyArrow type with type_bound for flexible numeric input
+    - Dynamic output type computed in bind()
+
     Example:
-        Input:  x=[1, 2, 3]
-        Args:   column="x"
+        SQL:    SELECT double_column(price) FROM products
+        Input:  price=[1, 2, 3]
         Output: result=[2, 4, 6]
 
     """
@@ -145,7 +146,6 @@ class Meta:
 
         name = "double_column"
         description = "Doubles values in a numeric column"
-        output_type = AnyArrow  # Output type depends on input column type
         examples = [
             FunctionExample(
                 sql="SELECT double_column(price) FROM products",
@@ -157,37 +157,42 @@ class Meta:
             ),
         ]
 
-    # Explicit arrow_type demonstrates type specification
-    column: Annotated[
-        AnyArrowValue, Arg(0, doc="Value to double", type_bound=_is_addable_type)
-    ]
+    _output_type: pa.DataType
 
     def bind(self) -> None:
         """Compute output type from input column types."""
-        field1 = self.input_schema.field(self.column.value)
-
-        # Since we're going to be multiplying by 2, promote to a wider type
-        self._output_type = _promote_for_addition(field1.type)
+        # Get the input column type from the schema
+        field = self.input_schema.field(0)
+        # Promote to a wider type since we're multiplying by 2
+        self._output_type = _promote_for_addition(field.type)
 
     @property
     def output_type(self) -> pa.DataType:
         """Return the type of the doubled column."""
         return self._output_type
 
-    def compute(self, *, column: pa.Array[Any]) -> pa.Array[Any]:
+    def compute(
+        self,
+        column: Param(AnyArrow, "Numeric value to double", type_bound=_is_addable_type),  # type: ignore[valid-type]
+    ) -> pa.Array[Any]:
         """Double the values in the specified column."""
-        return pc.multiply(column, 2)
+        result: pa.Array[Any] = pc.multiply(column, 2)
+        return result
 
 
 class AddNumericColumnsFunction(ScalarFunction):
     """Adds two numeric columns together.
 
+    This example demonstrates:
+    - Multiple Param() annotations with type_bound validation
+    - Dynamic output type with type promotion for overflow safety
+
     Validates that both columns are numeric types (integer, float, decimal, or
-    temporal) at bind time, raising SchemaValidationError if not.
+    temporal) at compute time, raising SchemaValidationError if not.
 
     Example:
-        Input:  a=[1, 2, 3], b=[10, 20, 30]
-        Args:   col1="a", col2="b"
+        SQL:    SELECT add_columns(price, tax) FROM orders
+        Input:  price=[1, 2, 3], tax=[10, 20, 30]
         Output: result=[11, 22, 33]
 
     Raises:
@@ -200,7 +205,6 @@ class Meta:
 
         name = "add_columns"
         description = "Adds two numeric columns"
-        output_type = AnyArrow  # Output type depends on input column types
         examples = [
             FunctionExample(
                 sql="SELECT add_columns(price, tax) FROM orders",
@@ -212,25 +216,15 @@ class Meta:
             ),
         ]
 
-    # type_bound validates value types at bind time (automatic via Function.__init__)
-    col1: Annotated[
-        AnyArrowValue, Arg(0, doc="First numeric value", type_bound=_is_addable_type)
-    ]
-    col2: Annotated[
-        AnyArrowValue, Arg(1, doc="Second numeric value", type_bound=_is_addable_type)
-    ]
-
     _output_type: pa.DataType
 
     def bind(self) -> None:
         """Compute output type from input column types."""
-        field1 = self.input_schema.field(self.col1.value)
-        field2 = self.input_schema.field(self.col2.value)
+        field1 = self.input_schema.field(0)
+        field2 = self.input_schema.field(1)
 
         # Compute the output type by promoting to the wider of the two types,
         # then promoting again to reduce overflow risk.
-        # Use pc.add with null values to determine the common type, as PyArrow's
-        # compute functions handle type promotion correctly.
         common_type = pc.add(
             pa.nulls(1, type=field1.type), pa.nulls(1, type=field2.type)
         ).type
@@ -241,9 +235,14 @@ def output_type(self) -> pa.DataType:
         """Return the computed output type based on input column types."""
         return self._output_type
 
-    def compute(self, *, col1: pa.Array[Any], col2: pa.Array[Any]) -> pa.Array[Any]:
+    def compute(
+        self,
+        col1: Param(AnyArrow, "First numeric value", type_bound=_is_addable_type),  # type: ignore[valid-type]
+        col2: Param(AnyArrow, "Second numeric value", type_bound=_is_addable_type),  # type: ignore[valid-type]
+    ) -> pa.Array[Any]:
         """Add the two columns together."""
-        return pc.add(col1, col2)
+        result: pa.Array[Any] = pc.add(col1, col2)
+        return result
 
 
 class UpperCaseFunction(ScalarFunction):
@@ -285,12 +284,14 @@ def compute(
 class SumColumnsFunction(ScalarFunction):
     """Sums values from multiple numeric columns.
 
-    Uses varargs with type_bound to accept any number of numeric columns
-    and validates that all columns are addable types at bind time.
+    This example demonstrates:
+    - varargs=True to accept variable number of columns
+    - type_bound validation on all varargs columns
+    - Dynamic output type computed in bind()
 
     Example:
-        Input:  a=[1, 2], b=[10, 20], c=[100, 200]
-        Args:   columns=('a', 'b', 'c')
+        SQL:    SELECT sum_columns(price, tax, shipping) FROM orders
+        Input:  price=[1, 2], tax=[10, 20], shipping=[100, 200]
         Output: result=[111, 222]
 
     """
@@ -300,43 +301,33 @@ class Meta:
 
         name = "sum_columns"
         description = "Sum values from multiple numeric columns"
-        output_type = AnyArrow  # Output type depends on input column types
         examples = [
             FunctionExample(
                 sql="SELECT sum_columns(price, tax, shipping) FROM orders",
                 description="Calculate total cost from multiple columns",
             ),
         ]
 
-    # Varargs with type_bound validates all values are numeric
-    # Note: varargs returns tuple[Any, ...], not AnyArrowValue
-    columns: Annotated[
-        tuple[Any, ...],
-        Arg(
-            0,
-            varargs=True,
-            type_bound=_is_addable_type,
-            doc="Numeric values to sum",
-        ),
-    ]
-
     _output_type: pa.DataType
 
     def bind(self) -> None:
         """Compute output type from first column, promoted for overflow safety."""
-        # With varargs=True, self.columns is a tuple of column names
-        first_col = self.columns[0]  # type: ignore[index]
-        first_type = self.input_schema.field(first_col).type
+        first_type = self.input_schema.field(0).type
         self._output_type = _promote_for_addition(first_type)
 
     @property
     def output_type(self) -> pa.DataType:
         """Return the computed output type based on first column."""
         return self._output_type
 
-    def compute(self, *, columns: list[pa.Array[Any]]) -> pa.Array[Any]:
+    def compute(
+        self,
+        columns: Param(  # type: ignore[valid-type]
+            AnyArrow, "Numeric values to sum", type_bound=_is_addable_type, varargs=True
+        ),
+    ) -> pa.Array[Any]:
         """Sum values from all specified columns."""
-        result = columns[0]
+        result: pa.Array[Any] = columns[0]
         for col in columns[1:]:
             result = pc.add(result, col)
         return result

vgi/scalar_function.py

@@ -980,31 +980,31 @@ def _extract_compute_kwargs(self, batch: pa.RecordBatch) -> dict[str, Any]:
     def _validate_param_types(self, kwargs: dict[str, Any]) -> None:
         """Validate that input array types match declared Param types.
 
-        Only validates for the new Param/ConstParam API, and only for params
-        that have a declared arrow_type (not is_any=True).
+        For the new Param/ConstParam API:
+        - Validates exact type match for params with declared arrow_type
+        - Validates type_bound predicates for AnyArrow params with type_bound
 
         Args:
             kwargs: Dict of parameter names to arrays (from _extract_compute_kwargs).
 
         Raises:
             TypeMismatchError: If any array type doesn't match its declared type.
+            SchemaValidationError: If any array type fails type_bound validation.
 
         """
         if not self._uses_new_param_api:
-            return  # Legacy API doesn't have explicit type declarations
+            return  # Legacy API uses _validate_type_bounds in Function.__init__
 
         for name, arg in self._compute_params.items():
-            if arg.is_any:
-                continue  # Skip AnyArrow params
-
-            if arg.arrow_type is None:
-                continue  # No type declared (shouldn't happen with new API)
-
             if arg.varargs:
                 # Validate all arrays in varargs
                 arrays = kwargs[name]
                 for i, arr in enumerate(arrays):
-                    if arr.type != arg.arrow_type:
+                    if arg.is_any:
+                        # AnyArrow: validate type_bound if specified
+                        if arg.type_bound is not None:
+                            arg.validate_type_bound(arr.type)
+                    elif arg.arrow_type is not None and arr.type != arg.arrow_type:
                         raise TypeMismatchError(
                             f"Input type mismatch for vararg parameter '{name}' "
                             f"at index {i}.",
@@ -1015,7 +1015,11 @@ def _validate_param_types(self, kwargs: dict[str, Any]) -> None:
                         )
             else:
                 arr = kwargs[name]
-                if arr.type != arg.arrow_type:
+                if arg.is_any:
+                    # AnyArrow: validate type_bound if specified
+                    if arg.type_bound is not None:
+                        arg.validate_type_bound(arr.type)
+                elif arg.arrow_type is not None and arr.type != arg.arrow_type:
                     raise TypeMismatchError(
                         f"Input type mismatch for parameter '{name}'.",
                         param_name=name,