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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.5
+Version: 0.8.7
 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
@@ -162,7 +162,7 @@ Requires-Dist: httpx>=0.24
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.20.5
+Requires-Dist: vgi-rpc>=0.21.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

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

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.8.5"
+version = "0.8.7"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [
@@ -40,7 +40,7 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.20.5",
+    "vgi-rpc>=0.21.0",
     "httpx>=0.24",
 ]
 

{vgi_python-0.8.5 → vgi_python-0.8.7}/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.7/tests/test_tcp_transport.py

@@ -0,0 +1,122 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Round-trip tests for the TCP transport.
+
+Spawns ``vgi-fixture-worker --tcp 127.0.0.1:0`` (raw Arrow-IPC framing over a
+TCP socket, served by ``vgi_rpc.rpc.run_server``), parses the ``TCP:host:port``
+discovery line it prints on stdout, then drives it through
+``Client.from_tcp(...)`` — the TCP analog of the HTTP round-trip in
+``tests/_http_fixtures.py``.
+"""
+
+from __future__ import annotations
+
+import queue
+import subprocess
+import sys
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import pyarrow as pa
+import pytest
+
+from vgi.arguments import Arguments
+from vgi.client import Client
+
+
+@contextmanager
+def run_tcp_worker(*, bind: str = "127.0.0.1:0") -> Iterator[tuple[str, int]]:
+    """Run ``vgi-fixture-worker --tcp`` and yield the bound ``(host, port)``.
+
+    The worker prints ``TCP:<host>:<port>`` once bound and then must not write
+    further to stdout (the cross-language launcher discovery contract), so we
+    read exactly one line to learn the port. stderr is drained in the
+    background to keep the worker from blocking on a full pipe buffer.
+    """
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "vgi._test_fixtures.worker", "--tcp", bind],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+
+    def _drain(pipe: object) -> None:
+        for _ in pipe:  # type: ignore[attr-defined]
+            pass
+
+    stderr_thread = threading.Thread(target=_drain, args=(proc.stderr,), daemon=True)
+    stderr_thread.start()
+
+    # Read the discovery line off stdout with a timeout so a worker that never
+    # binds fails the test instead of hanging it.
+    line_q: queue.Queue[str] = queue.Queue(maxsize=1)
+
+    def _read_line() -> None:
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            if line.startswith("TCP:"):
+                line_q.put(line.strip())
+                return
+
+    reader = threading.Thread(target=_read_line, daemon=True)
+    reader.start()
+    try:
+        discovery = line_q.get(timeout=30)
+    except queue.Empty:
+        proc.terminate()
+        raise TimeoutError("worker did not emit a TCP: discovery line within 30s") from None
+
+    _, host, port_str = discovery.split(":", 2)
+    try:
+        yield host, int(port_str)
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=5)
+        stderr_thread.join(timeout=5)
+
+
+def test_tcp_round_trip_table_function() -> None:
+    """A table function streams rows correctly over the TCP transport."""
+    with run_tcp_worker() as (host, port), Client.from_tcp(host, port) as client:
+        batches = list(
+            client.table_function(
+                function_name="sequence",
+                arguments=Arguments(positional=(pa.scalar(5),)),
+            )
+        )
+
+    table = pa.Table.from_batches(batches)
+    assert table.column("n").to_pylist() == [0, 1, 2, 3, 4]
+
+
+def test_tcp_round_trip_catalog_listing() -> None:
+    """Catalog discovery works over the TCP transport (catalog_mixin path)."""
+    with run_tcp_worker() as (host, port), Client.from_tcp(host, port) as client:
+        catalogs = client.catalogs()
+
+    assert any(c.name == "example" for c in catalogs)
+
+
+class TestTcpConstructorValidation:
+    """``transport='tcp'`` argument validation."""
+
+    def test_requires_host_and_port(self) -> None:
+        """Tcp transport without host/port is rejected."""
+        with pytest.raises(ValueError, match="requires tcp_host and tcp_port"):
+            Client(transport="tcp", pool=None)
+
+    def test_rejects_server_path(self) -> None:
+        """server_path is subprocess-only."""
+        with pytest.raises(ValueError, match="server_path is only meaningful"):
+            Client("some-worker", transport="tcp", tcp_host="127.0.0.1", tcp_port=1, pool=None)
+
+    def test_rejects_base_url(self) -> None:
+        """base_url is http-only."""
+        with pytest.raises(ValueError, match="base_url is only meaningful"):
+            Client(transport="tcp", tcp_host="127.0.0.1", tcp_port=1, base_url="http://x", pool=None)

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

@@ -2250,7 +2250,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.8.4"
+version = "0.8.7"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2360,7 +2360,7 @@ requires-dist = [
     { name = "vgi-python", extras = ["test-fixtures"], marker = "extra == 'test-fixtures-writable'" },
     { name = "vgi-python", extras = ["test-fixtures", "test-fixtures-writable", "http", "oauth", "otel", "sentry", "azure"], marker = "extra == 'dev'" },
     { name = "vgi-python", extras = ["transactor"], marker = "extra == 'test-fixtures-writable'" },
-    { name = "vgi-rpc", specifier = ">=0.20.5" },
+    { name = "vgi-rpc", specifier = ">=0.21.0" },
     { name = "vgi-rpc", extras = ["conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'http'" },
     { name = "vgi-rpc", extras = ["oauth"], marker = "extra == 'oauth'" },
@@ -2389,7 +2389,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.20.6"
+version = "0.21.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2397,9 +2397,9 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/40/76/4a2c35af34928c6ab17fcb9b1b50639241bf9d015d45b23ce004d0d70d51/vgi_rpc-0.20.6.tar.gz", hash = "sha256:3172d5041b901b0d1a32c9b45da32363195bbca18adb7e305456f19c241cf8fe", size = 847271, upload-time = "2026-06-22T18:24:18.969Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/3d/7b/0de17f5f638414188829f8bb4952e9a6116145ad402512ead8d0f035b705/vgi_rpc-0.21.0.tar.gz", hash = "sha256:c82c17149c0977080184d4728bdebe38aebcd1374984f6c81a3ce39be0aca367", size = 857916, upload-time = "2026-06-26T00:05:14.045Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d3/3c/9ccc888e725ad9d7091e8ec6fd7504eec15dc2ccfabedabd7d072123b0e8/vgi_rpc-0.20.6-py3-none-any.whl", hash = "sha256:74f8b7c0685f1c28a3ff754d76f8c0179c782e33aa5915ad0343bb9955d7509d", size = 371735, upload-time = "2026-06-22T18:24:17.458Z" },
+    { url = "https://files.pythonhosted.org/packages/40/71/1607a7b093e2477d64a0193d21ec9b9fdfe8bc09f0165ce378fc214ef0a9/vgi_rpc-0.21.0-py3-none-any.whl", hash = "sha256:5e5b1ef8585f459eb0761c9232a6e4eeedef69be7b61ead61e0993f4a15b8698", size = 378442, upload-time = "2026-06-26T00:05:11.821Z" },
 ]
 
 [package.optional-dependencies]

{vgi_python-0.8.5 → vgi_python-0.8.7}/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.7}/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.7}/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.7}/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.7}/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,
+            ),
         )