Fix ConstParam type inference and improve documentation

- Fix metadata extraction to properly infer types from ConstParam annotations
  (was hardcoded as "double", now infers from Annotated[type, ...])
- Add clarifying comments in PolarsMultiplyFunction explaining the
  class attribute vs property pattern for ConstParam
- Update docs/polars-scalar-functions.md with proper ConstParam pattern
  including the metadata declaration and runtime value access

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

Author: rustyconover

docs/polars-scalar-functions.md

@@ -195,26 +195,38 @@ class SumAll(PolarsScalarFunction):
 
 ## Constant Arguments
 
-Access scalar values passed in SQL (not from table columns):
+Use `ConstParam` to declare scalar values passed in SQL (not from table columns).
+This ensures the argument appears in function metadata for catalog registration.
 
 ```python
+from vgi import ConstParam
+
 class Multiply(PolarsScalarFunction):
-    value: Annotated[pl.Float64, Param(position=0, doc="Column")]
+    # Column binding: input column at position 0
+    value: Annotated[pl.Float64, Param(position=0, doc="Column to multiply")]
+
+    # ConstParam declaration: scalar argument at position 0 in function call
+    # This is a type annotation for metadata - use _factor property to access value
+    factor: Annotated[float, ConstParam("Multiplication factor", position=0)]
 
     class Meta:
         output_type = pl.Float64
 
     @property
-    def factor(self) -> float:
-        """Get constant from SQL arguments."""
+    def _factor(self) -> float:
+        """Get constant from SQL arguments at runtime."""
         return self.invocation.arguments.positional[0].as_py()
 
     def compute_polars(self) -> pl.Expr:
-        return pl.col("value") * self.factor
+        return pl.col("value") * self._factor
 ```
 
 SQL usage: `SELECT polars_multiply(price, 1.1) FROM products`
 
+**Important**: The `ConstParam` class attribute is a type annotation for metadata
+extraction only. To access the actual value at runtime, use a property that reads
+from `self.invocation.arguments.positional[position]`.
+
 ## Meta Class Options
 
 ```python

vgi/examples/scalar_polars.py

@@ -277,7 +277,12 @@ class PolarsMultiplyFunction(PolarsScalarFunction):
 
     """
 
+    # Column binding: maps input column at position 0 to "value" in expression
     value: Annotated[pl.Float64, Param(position=0, doc="Value to multiply")]
+
+    # ConstParam declaration for metadata extraction (tells catalog about the argument).
+    # The actual value is accessed via _factor property below since class-level
+    # Annotated declarations are type hints only, not instance attributes.
     factor: Annotated[float, ConstParam("Multiplication factor", position=0)]
 
     class Meta:

vgi/metadata.py

@@ -46,14 +46,15 @@ def transform(self, batch):
 
 from __future__ import annotations
 
+import contextlib
 import functools
 import json
 import re
 import warnings
 from collections.abc import Sequence
 from dataclasses import dataclass, field
 from enum import Enum, auto
-from typing import TYPE_CHECKING, Any, get_type_hints
+from typing import TYPE_CHECKING, Annotated, Any, get_args, get_origin, get_type_hints
 
 import pyarrow as pa
 
@@ -486,26 +487,55 @@ def extract_parameters(
     # However, ConstParam entries (is_const=True) ARE function arguments and must
     # be extracted for the function signature.
     polars_params = getattr(cls, "_polars_params", {})
-    for name, param_info in polars_params.items():
-        if not param_info.is_const:
-            continue  # Skip column bindings, only extract ConstParam
-        seen_names.add(name)
-        # ConstParam is always required (no default support currently)
-        type_name = "double"  # TODO: Infer from annotation type
-        parameters.append(
-            ParameterInfo(
-                name=name,
-                position=param_info.position,
-                type_name=type_name,
-                description=param_info.doc,
-                required=True,
-                default=None,
-                constraints=None,
-                is_table_input=False,
-                is_varargs=False,
-                is_const=True,
+    if polars_params:
+        # Get class annotations to infer ConstParam types
+        annotations = getattr(cls, "__annotations__", {})
+        for name, param_info in polars_params.items():
+            if not param_info.is_const:
+                continue  # Skip column bindings, only extract ConstParam
+            seen_names.add(name)
+
+            # Infer type from annotation (e.g., Annotated[float, ConstParam(...)])
+            type_name = "any"
+            if name in annotations:
+                hint = annotations[name]
+                # Handle string annotations (from __future__ import annotations)
+                if isinstance(hint, str):
+                    # Build namespace with builtins, typing constructs, and ConstParam
+                    import builtins
+
+                    from vgi.arguments import ConstParam
+
+                    eval_ns = dict(vars(builtins))
+                    eval_ns["Annotated"] = Annotated
+                    eval_ns["ConstParam"] = ConstParam
+                    with contextlib.suppress(Exception):
+                        hint = eval(hint, eval_ns)  # noqa: S307
+                # Extract base type from Annotated[base_type, ...]
+                base_type = get_args(hint)[0] if get_origin(hint) is Annotated else hint
+                # Map Python types to Arrow type names
+                python_to_arrow = {
+                    float: "double",
+                    int: "int64",
+                    str: "string",
+                    bool: "bool",
+                }
+                type_name = python_to_arrow.get(base_type, "any")
+
+            parameters.append(
+                ParameterInfo(
+                    name=name,
+                    position=param_info.position,
+                    type_name=type_name,
+                    description=param_info.doc,
+                    required=True,  # ConstParam is always required
+                    default=None,
+                    constraints=None,
+                    is_table_input=False,
+                    is_varargs=False,
+                    is_const=True,
+                )
             )
-        )
 
     # Check for new Param/ConstParam API (ScalarFunction subclasses)
     # These are stored in _compute_params and _const_params class attributes