vgi-python 0.8.5__tar.gz → 0.8.6__tar.gz

{vgi_python-0.8.5 → vgi_python-0.8.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.5
+Version: 0.8.6
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python

{vgi_python-0.8.5 → vgi_python-0.8.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.8.5"
+version = "0.8.6"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [

{vgi_python-0.8.5 → vgi_python-0.8.6}/tests/catalog/test_serialization.py

@@ -615,6 +615,140 @@ class TestMacroInfoSerialization:
             restored = MacroInfo.deserialize_from_batch(batch)
             assert restored.macro_type == macro_type
 
+    def test_arguments_schema_round_trip(self) -> None:
+        """arguments_schema carries vgi_doc per documented param; absent doc -> no key."""
+        from vgi.argument_spec import VGI_DOC_KEY, macro_arguments_schema, macro_parameter_docs_from_schema
+
+        defaults = pa.RecordBatch.from_pydict({"lo": pa.array([0], type=pa.int64())})
+        args = macro_arguments_schema(
+            parameters=["val", "lo", "hi"],
+            parameter_default_values=defaults,
+            parameter_docs={"val": "value to clamp", "hi": "upper bound"},
+        )
+        original = MacroInfo(
+            name="clamp",
+            schema_name="main",
+            macro_type=MacroType.SCALAR,
+            parameters=["val", "lo", "hi"],
+            parameter_default_values=defaults,
+            definition="GREATEST(lo, LEAST(hi, val))",
+            comment=None,
+            tags={},
+            arguments_schema=args,
+        )
+        serialized = original.serialize_to_bytes()
+        batch, _ = deserialize_record_batch(serialized)
+        restored = MacroInfo.deserialize_from_batch(batch)
+
+        assert restored.arguments_schema is not None
+        rs = restored.arguments_schema
+        # One field per parameter, in order.
+        assert rs.names == ["val", "lo", "hi"]
+        # Field type tracks the default value type when known, else null.
+        assert rs.field("lo").type == pa.int64()
+        assert rs.field("val").type == pa.null()
+        assert rs.field("hi").type == pa.null()
+        # Documented params carry vgi_doc; undocumented (lo) has no key.
+        assert (rs.field("val").metadata or {}).get(VGI_DOC_KEY) == b"value to clamp"
+        assert (rs.field("hi").metadata or {}).get(VGI_DOC_KEY) == b"upper bound"
+        assert VGI_DOC_KEY not in (rs.field("lo").metadata or {})
+        # Convenience extractor returns only documented params.
+        assert macro_parameter_docs_from_schema(rs) == {"val": "value to clamp", "hi": "upper bound"}
+
+    def test_none_arguments_schema(self) -> None:
+        """arguments_schema defaults to None (older workers) and survives round-trip."""
+        original = MacroInfo(
+            name="simple",
+            schema_name="main",
+            macro_type=MacroType.SCALAR,
+            parameters=["x"],
+            definition="x",
+            comment=None,
+            tags={},
+        )
+        serialized = original.serialize_to_bytes()
+        batch, _ = deserialize_record_batch(serialized)
+        restored = MacroInfo.deserialize_from_batch(batch)
+        assert restored.arguments_schema is None
+
+
+class TestMacroArgumentsSchemaWire:
+    """Macro per-parameter docs flow over create/list wire types."""
+
+    def test_declarative_macro_to_info_carries_docs(self) -> None:
+        """Declarative Macro.parameter_docs -> MacroInfo.arguments_schema vgi_doc."""
+        from vgi.argument_spec import macro_parameter_docs_from_schema
+        from vgi.catalog.descriptors import Macro
+
+        m = Macro(
+            name="clamp",
+            macro_type=MacroType.SCALAR,
+            parameters=["x", "lo", "hi"],
+            parameter_default_values=pa.RecordBatch.from_pydict(
+                {"lo": pa.array([0], type=pa.int64()), "hi": pa.array([100], type=pa.int64())}
+            ),
+            parameter_docs={"x": "value to clamp"},
+            definition="GREATEST(lo, LEAST(hi, x))",
+        )
+        info = m.to_macro_info("main")
+        assert info.arguments_schema is not None
+        assert info.arguments_schema.names == ["x", "lo", "hi"]
+        assert macro_parameter_docs_from_schema(info.arguments_schema) == {"x": "value to clamp"}
+
+    def test_declarative_macro_rejects_unknown_doc_param(self) -> None:
+        """parameter_docs keys must be in parameters (validated like defaults)."""
+        from vgi.catalog.descriptors import Macro
+
+        with pytest.raises(ValueError, match="documented parameter 'bogus' not found"):
+            Macro(
+                name="bad",
+                macro_type=MacroType.SCALAR,
+                parameters=["x"],
+                parameter_docs={"bogus": "nope"},
+                definition="x",
+            )
+
+    def test_macro_create_request_round_trip(self) -> None:
+        """MacroCreateRequest carries arguments_schema over the wire."""
+        from vgi.argument_spec import macro_arguments_schema, macro_parameter_docs_from_schema
+        from vgi.catalog import OnConflict
+        from vgi.protocol import MacroCreateRequest
+
+        args = macro_arguments_schema(
+            parameters=["x", "y"],
+            parameter_docs={"x": "first", "y": "second"},
+        )
+        req = MacroCreateRequest(
+            attach_opaque_data=b"attach",
+            schema_name="main",
+            name="add",
+            macro_type=MacroType.SCALAR,
+            parameters=["x", "y"],
+            definition="x + y",
+            on_conflict=OnConflict.ERROR,
+            arguments_schema=args,
+        )
+        restored = MacroCreateRequest.deserialize_from_bytes(req.serialize_to_bytes())
+        assert restored.arguments_schema is not None
+        assert macro_parameter_docs_from_schema(restored.arguments_schema) == {"x": "first", "y": "second"}
+
+    def test_macro_create_request_none_arguments_schema(self) -> None:
+        """MacroCreateRequest.arguments_schema defaults to None and round-trips."""
+        from vgi.catalog import OnConflict
+        from vgi.protocol import MacroCreateRequest
+
+        req = MacroCreateRequest(
+            attach_opaque_data=b"attach",
+            schema_name="main",
+            name="add",
+            macro_type=MacroType.SCALAR,
+            parameters=["x", "y"],
+            definition="x + y",
+            on_conflict=OnConflict.ERROR,
+        )
+        restored = MacroCreateRequest.deserialize_from_bytes(req.serialize_to_bytes())
+        assert restored.arguments_schema is None
+
 
 class TestFunctionInfoSerialization:
     """Test FunctionInfo serialization round-trip."""

{vgi_python-0.8.5 → vgi_python-0.8.6}/uv.lock

@@ -2250,7 +2250,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.8.4"
+version = "0.8.5"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/_test_fixtures/catalog.py

@@ -752,6 +752,7 @@ class InMemoryCatalog(CatalogInterface):
         definition: str,
         on_conflict: OnConflict,
         parameter_default_values: pa.RecordBatch | None = None,
+        arguments_schema: pa.Schema | None = None,
     ) -> None:
         """Create a new macro."""
         schema_data = self._get_schema(attach_opaque_data, schema_name)
@@ -773,6 +774,7 @@ class InMemoryCatalog(CatalogInterface):
                 definition=definition,
                 comment=None,
                 tags={},
+                arguments_schema=arguments_schema,
             )
         )
         self._increment_version(attach_opaque_data)

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/_test_fixtures/worker.py

@@ -519,6 +519,10 @@ _EXAMPLE_CATALOG = Catalog(
                     parameters=["x", "y"],
                     definition="x * y",
                     comment="Multiply two values",
+                    parameter_docs={
+                        "x": "First factor",
+                        "y": "Second factor",
+                    },
                 ),
                 Macro(
                     name="vgi_clamp",
@@ -530,6 +534,11 @@ _EXAMPLE_CATALOG = Catalog(
                     ),
                     definition="GREATEST(lo, LEAST(hi, val))",
                     comment="Clamp a value between lo and hi (defaults: 0..100)",
+                    parameter_docs={
+                        "val": "Value to clamp",
+                        "lo": "Lower bound (inclusive)",
+                        "hi": "Upper bound (inclusive)",
+                    },
                 ),
                 Macro(
                     name="vgi_range_table",
@@ -537,6 +546,7 @@ _EXAMPLE_CATALOG = Catalog(
                     parameters=["n"],
                     definition="SELECT * FROM range(n)",
                     comment="Table macro returning range of values",
+                    parameter_docs={"n": "Number of rows to generate"},
                 ),
             ],
         ),

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/argument_spec.py

@@ -27,6 +27,8 @@ __all__ = [
     "ArgumentSpec",
     "argument_specs_to_schema",
     "extract_argument_specs",
+    "macro_arguments_schema",
+    "macro_parameter_docs_from_schema",
     "schema_to_argument_specs",
     # Metadata constants for parsing schemas
     "VGI_ARG_KEY",
@@ -280,6 +282,86 @@ def schema_to_argument_specs(schema: pa.Schema) -> list[ArgumentSpec]:
     return specs
 
 
+# =============================================================================
+# Macro Argument Schemas
+# =============================================================================
+
+
+def macro_arguments_schema(
+    parameters: Sequence[str],
+    parameter_default_values: pa.RecordBatch | None = None,
+    parameter_docs: dict[str, str] | None = None,
+) -> pa.Schema:
+    """Build a macro ``arguments_schema`` describing macro parameters.
+
+    Mirrors the function ``arguments_schema`` mechanism: one Arrow field per
+    macro parameter, in ``parameters`` order, each nullable. The per-parameter
+    description is carried via the same ``vgi_doc`` field-metadata key functions
+    use (UTF-8, presence-only — the key is omitted entirely when there is no
+    doc). A parameter's field type is the type of its default value when one is
+    known (from ``parameter_default_values``), else ``pa.null()``.
+
+    Args:
+        parameters: Ordered list of macro parameter names.
+        parameter_default_values: Optional one-row ``RecordBatch`` whose columns
+            are parameter names with typed default values; used to infer each
+            parameter's field type.
+        parameter_docs: Optional mapping of parameter name to description. Empty
+            or missing descriptions yield no ``vgi_doc`` metadata on the field.
+
+    Returns:
+        Arrow schema with one nullable field per parameter, in order.
+
+    """
+    docs = parameter_docs or {}
+
+    # Map parameter name -> Arrow type from the typed default values, if any.
+    default_types: dict[str, pa.DataType] = {}
+    if parameter_default_values is not None:
+        for default_field in parameter_default_values.schema:
+            default_types[default_field.name] = default_field.type
+
+    fields: list[pa.Field[Any]] = []
+    for name in parameters:
+        metadata: dict[bytes, bytes] = {}
+        doc = docs.get(name, "")
+        if doc:
+            metadata[VGI_DOC_KEY] = doc.encode("utf-8")
+
+        field = pa.field(
+            name,
+            default_types.get(name, pa.null()),
+            nullable=True,
+            metadata=metadata if metadata else None,
+        )
+        fields.append(field)
+
+    return pa.schema(fields)
+
+
+def macro_parameter_docs_from_schema(schema: pa.Schema) -> dict[str, str]:
+    """Extract per-parameter descriptions from a macro ``arguments_schema``.
+
+    Inverse of [`macro_arguments_schema`][]'s ``vgi_doc`` handling: reads the
+    ``vgi_doc`` field metadata (UTF-8) for each field. Fields without the key
+    (undocumented) are omitted from the result.
+
+    Args:
+        schema: A macro ``arguments_schema`` (one field per parameter).
+
+    Returns:
+        Mapping of parameter name to description, for documented parameters only.
+
+    """
+    docs: dict[str, str] = {}
+    for field in schema:
+        metadata = field.metadata or {}
+        doc_bytes = metadata.get(VGI_DOC_KEY)
+        if doc_bytes:
+            docs[field.name] = doc_bytes.decode("utf-8")
+    return docs
+
+
 # =============================================================================
 # Extraction from Function Classes
 # =============================================================================

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/catalog/catalog_interface.py

@@ -435,6 +435,15 @@ class MacroInfo(CatalogSchemaObject, ArrowSerializableDataclass):
             names and values are typed defaults. None if no defaults.
             Serialized as IPC bytes over the wire.
         definition: The SQL expression (scalar) or query (table).
+        arguments_schema: Optional Arrow schema (serialized as IPC bytes) with one
+            nullable field per parameter, in ``parameters`` order. Each field's type
+            is the parameter's default value type when known (else null), and the
+            ``vgi_doc`` field metadata key carries the parameter's description (UTF-8,
+            presence-only — omitted when undocumented). Mirrors the per-argument doc
+            channel functions expose via ``FunctionInfo.arguments``. None means the
+            worker did not supply per-parameter docs (older workers); the extension
+            falls back to ``parameters`` for names. Built with
+            ``vgi.argument_spec.macro_arguments_schema``.
 
     """
 
@@ -442,6 +451,7 @@ class MacroInfo(CatalogSchemaObject, ArrowSerializableDataclass):
     parameters: list[str]
     parameter_default_values: Annotated[pa.RecordBatch | None, ArrowType(pa.binary())] = None
     definition: str = ""
+    arguments_schema: Annotated[pa.Schema | None, ArrowType(pa.binary())] = None
 
 
 class FunctionType(Enum):
@@ -1979,8 +1989,25 @@ class CatalogInterface(ABC):
         definition: str,
         on_conflict: OnConflict,
         parameter_default_values: pa.RecordBatch | None = None,
+        arguments_schema: pa.Schema | None = None,
     ) -> None:
-        """Create a new macro with the given definition."""
+        """Create a new macro with the given definition.
+
+        Args:
+            attach_opaque_data: Per-attach catalog session token.
+            transaction_opaque_data: Optional transaction handle.
+            schema_name: Schema to create the macro in.
+            name: Name for the new macro.
+            macro_type: Whether this is a scalar or table macro.
+            parameters: Ordered list of parameter names.
+            definition: SQL expression (scalar) or query (table).
+            on_conflict: Behavior if the macro already exists.
+            parameter_default_values: One-row ``RecordBatch`` with typed defaults.
+            arguments_schema: Optional Arrow schema (one nullable field per
+                parameter, in ``parameters`` order) carrying per-parameter
+                descriptions via the ``vgi_doc`` field metadata key. ``None`` when
+                no per-parameter docs are supplied.
+        """
         raise NotImplementedError("Macro create not implemented.")
 
     def macro_drop(

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/catalog/descriptors.py

@@ -18,6 +18,7 @@ from typing import TYPE_CHECKING, Any, Union
 
 import pyarrow as pa
 
+from vgi.argument_spec import macro_arguments_schema
 from vgi.arguments import Arguments
 from vgi.catalog.catalog_interface import (
     AttachOpaqueData,
@@ -695,6 +696,11 @@ class Macro:
         parameter_default_values: One-row `RecordBatch` where columns are parameter
             names and values are typed defaults. None if no defaults.
             Example: pa.RecordBatch.from_pydict({"b": [5]}) for b := 5.
+        parameter_docs: Optional mapping of parameter name to a human/agent-facing
+            description. Keys must appear in ``parameters``. Descriptions flow over
+            the wire via the macro ``arguments_schema``'s ``vgi_doc`` field metadata
+            (the same channel functions use), so the DuckDB extension's
+            ``vgi_function_arguments()`` can surface them. Empty/default = no docs.
         definition: SQL expression (scalar) or query (table).
         comment: Optional macro comment.
         tags: Optional metadata tags.
@@ -705,12 +711,14 @@ class Macro:
     macro_type: MacroType
     parameters: list[str] = field(default_factory=list)
     parameter_default_values: pa.RecordBatch | None = None
+    parameter_docs: dict[str, str] = field(default_factory=dict)
     definition: str = ""
     comment: str | None = None
     tags: dict[str, str] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
         """Validate macro configuration."""
+        param_set = set(self.parameters)
         if self.parameter_default_values is not None:
             if self.parameter_default_values.num_rows != 1:
                 raise ValueError(
@@ -718,13 +726,19 @@ class Macro:
                     f"got {self.parameter_default_values.num_rows}"
                 )
             # Validate that default param column names exist in parameters list
-            param_set = set(self.parameters)
             for col_name in self.parameter_default_values.schema.names:
                 if col_name not in param_set:
                     raise ValueError(
                         f"Macro '{self.name}': default parameter '{col_name}' not found "
                         f"in parameters list {self.parameters}"
                     )
+        # Validate that documented parameter names exist in parameters list
+        for doc_name in self.parameter_docs:
+            if doc_name not in param_set:
+                raise ValueError(
+                    f"Macro '{self.name}': documented parameter '{doc_name}' not found "
+                    f"in parameters list {self.parameters}"
+                )
 
     def to_macro_info(self, schema_name: str) -> MacroInfo:
         """Convert to [`MacroInfo`][] for catalog response."""
@@ -737,6 +751,11 @@ class Macro:
             definition=self.definition,
             comment=self.comment,
             tags=dict(self.tags),
+            arguments_schema=macro_arguments_schema(
+                self.parameters,
+                self.parameter_default_values,
+                self.parameter_docs,
+            ),
         )
 
 

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/client/catalog_mixin.py

@@ -1196,6 +1196,7 @@ class CatalogClientMixin:
         definition: str,
         on_conflict: OnConflict = OnConflict.ERROR,
         parameter_default_values: pa.RecordBatch | None = None,
+        arguments_schema: pa.Schema | None = None,
     ) -> None:
         """Create a new macro.
 
@@ -1209,6 +1210,10 @@ class CatalogClientMixin:
             definition: SQL expression (scalar) or query (table).
             on_conflict: Behavior if macro already exists.
             parameter_default_values: One-row `RecordBatch` with typed defaults.
+            arguments_schema: Optional Arrow schema (one nullable field per
+                parameter, in ``parameters`` order) carrying per-parameter
+                descriptions via the ``vgi_doc`` field metadata key. Build with
+                ``vgi.argument_spec.macro_arguments_schema``.
 
         """
         with self._catalog_connect() as proxy:
@@ -1222,6 +1227,7 @@ class CatalogClientMixin:
                     definition=definition,
                     on_conflict=on_conflict,
                     parameter_default_values=parameter_default_values,
+                    arguments_schema=arguments_schema,
                     transaction_opaque_data=transaction_opaque_data,
                 )
             )

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/codegen/go_schemas.py

@@ -155,8 +155,14 @@ def _emit_field_literal(field: pa.Field[Any], *, origin: str) -> str:
 
 def _emit_var(es: EmittedSchema) -> str:
     body = f"// Origin: {es.origin}\n"
+    fields = list(es.schema)
+    # Empty schemas must collapse to `[]arrow.Field{}` on one line — gofmt
+    # rejects the multi-line `{\n}` form, and vgi-go's CI runs `gofmt -l`.
+    if not fields:
+        body += f"var {es.name}Schema = arrow.NewSchema([]arrow.Field{{}}, nil)\n"
+        return body
     body += f"var {es.name}Schema = arrow.NewSchema([]arrow.Field{{\n"
-    for f in es.schema:
+    for f in fields:
         body += "\t" + _emit_field_literal(f, origin=f"{es.name}.{f.name}") + ",\n"
     body += "}, nil)\n"
     return body
@@ -178,9 +184,9 @@ def emit(out: TextIO) -> None:
     body.write("\n")
     body.write("var _ = arrow.BinaryTypes.String // keep import live when no schemas reference it\n")
     body.write("\n")
-    for block in (_emit_var(es) for es in schemas):
-        body.write(block)
-        body.write("\n")
+    # Blank line BETWEEN blocks, but no trailing blank line at EOF (gofmt rejects
+    # it; vgi-go CI runs `gofmt -l`). Each block already ends in "\n".
+    body.write("\n".join(_emit_var(es) for es in schemas))
 
     out.write(
         provenance_comment(

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/protocol.py

@@ -562,6 +562,13 @@ class MacroCreateRequest(ArrowSerializableDataclass):
             ERROR/IGNORE/REPLACE).
         parameter_default_values: One-row `RecordBatch` where column names are
             parameter names and values are typed defaults; ``None`` if no defaults.
+        arguments_schema: Optional Arrow schema (serialized as IPC bytes) with one
+            nullable field per parameter, in ``parameters`` order. Each field's type
+            is the parameter's default value type when known (else null), and the
+            ``vgi_doc`` field metadata key carries the parameter's description (UTF-8,
+            presence-only — omitted when undocumented). Mirrors the per-argument doc
+            channel functions expose. ``None`` when no per-parameter docs are
+            supplied. Built with ``vgi.argument_spec.macro_arguments_schema``.
         transaction_opaque_data: Opaque DuckDB transaction handle (bytes); ``None``
             when not inside a transaction.
     """
@@ -574,6 +581,7 @@ class MacroCreateRequest(ArrowSerializableDataclass):
     definition: str
     on_conflict: OnConflict
     parameter_default_values: Annotated[pa.RecordBatch | None, ArrowType(pa.binary())] = None
+    arguments_schema: Annotated[pa.Schema | None, ArrowType(pa.binary())] = None
     transaction_opaque_data: bytes | None = None
 
 

{vgi_python-0.8.5 → vgi_python-0.8.6}/vgi/worker.py

@@ -4438,6 +4438,7 @@ class Worker:
             definition=request.definition,
             on_conflict=request.on_conflict,
             parameter_default_values=request.parameter_default_values,
+            arguments_schema=request.arguments_schema,
         )
 
     def catalog_macro_drop(