vgi-python 0.8.5__py3-none-any.whl → 0.8.7__py3-none-any.whl

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/_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/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/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/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/client/catalog_mixin.py

@@ -90,12 +90,14 @@ class CatalogClientMixin:
     Catalog methods spawn ephemeral connections under the hood — for
     subprocess transport a pooled subprocess worker; for HTTP transport a
     short-lived ``http_connect`` session reusing the ``Client``'s shared
-    ``httpx.Client`` (bearer token, headers). Browsing catalogs over HTTP
-    is the canonical non-DuckDB use case this mixin supports.
+    ``httpx.Client`` (bearer token, headers); for TCP transport a short-lived
+    ``tcp_connect`` session. Browsing catalogs over HTTP is the canonical
+    non-DuckDB use case this mixin supports.
 
-    Other attributes expected from ``Client``: ``_transport`` (subprocess vs
-    http), ``_base_url`` (HTTP base URL), and ``_get_or_create_httpx_client()``
-    (shared HTTP client factory).
+    Other attributes expected from ``Client``: ``_transport`` (subprocess,
+    http, or tcp), ``_base_url`` (HTTP base URL), ``_tcp_host`` / ``_tcp_port``
+    (TCP endpoint), and ``_get_or_create_httpx_client()`` (shared HTTP client
+    factory).
 
     Attributes:
         server_path: Worker shell command used for subprocess transport.
@@ -103,8 +105,10 @@ class CatalogClientMixin:
 
     # Type hints for attributes expected from Client
     server_path: str
-    _transport: Literal["subprocess", "http"]
+    _transport: Literal["subprocess", "http", "tcp"]
     _base_url: str | None
+    _tcp_host: str | None
+    _tcp_port: int | None
     _external_location: Any | None
 
     def _get_or_create_httpx_client(self) -> Any:  # implemented by Client
@@ -128,7 +132,8 @@ class CatalogClientMixin:
             A typed `[`VgiProtocol`][]` proxy bound to the active transport.
         """
         try:
-            if getattr(self, "_transport", "subprocess") == "http":
+            transport = getattr(self, "_transport", "subprocess")
+            if transport == "http":
                 from vgi_rpc.http import http_connect
 
                 httpx_client = self._get_or_create_httpx_client()
@@ -139,6 +144,17 @@ class CatalogClientMixin:
                     external_location=getattr(self, "_external_location", None),
                 ) as proxy:
                     yield proxy
+            elif transport == "tcp":
+                from vgi_rpc.rpc import tcp_connect
+
+                assert self._tcp_host is not None and self._tcp_port is not None
+                with tcp_connect(
+                    VgiProtocol,  # type: ignore[type-abstract]
+                    self._tcp_host,
+                    self._tcp_port,
+                    external_location=getattr(self, "_external_location", None),
+                ) as proxy:
+                    yield proxy
             else:
                 cmd = shlex.split(self.server_path, posix=sys.platform != "win32")
                 with _catalog_pool.connect(VgiProtocol, cmd) as proxy:  # type: ignore[type-abstract]
@@ -1196,6 +1212,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 +1226,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 +1243,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/client/client.py

@@ -197,10 +197,10 @@ _HTTP_TRANSPORT_READY = True
 
 @dataclass
 class WorkerConnection:
-    """Holds state for a single worker connection (subprocess or HTTP).
+    """Holds state for a single worker connection (subprocess, HTTP, or TCP).
 
-    Exactly one of {proc+connection, _pool_ctx, _http_ctx} is active per
-    connection — transport-specific teardown inspects these fields.
+    Exactly one of {proc+connection, _pool_ctx, _http_ctx, _tcp_ctx} is active
+    per connection — transport-specific teardown inspects these fields.
 
     Attributes:
         proxy: The typed `[`VgiProtocol`][]` proxy used to invoke the worker.
@@ -220,6 +220,8 @@ class WorkerConnection:
     _pool_ctx: AbstractContextManager[Any] | None = field(default=None, repr=False)
     # HTTP transport: context manager from vgi_rpc.http.http_connect.
     _http_ctx: AbstractContextManager[Any] | None = field(default=None, repr=False)
+    # TCP transport: context manager from vgi_rpc.rpc.tcp_connect.
+    _tcp_ctx: AbstractContextManager[Any] | None = field(default=None, repr=False)
 
 
 class Client(CatalogClientMixin):
@@ -381,8 +383,10 @@ class Client(CatalogClientMixin):
         attach_opaque_data: bytes | None = None,
         pool: WorkerPool | None = _default_pool,
         *,
-        transport: Literal["subprocess", "http"] = "subprocess",
+        transport: Literal["subprocess", "http", "tcp"] = "subprocess",
         base_url: str | None = None,
+        tcp_host: str | None = None,
+        tcp_port: int | None = None,
         bearer_token: str | None = None,
         httpx_client: Any | None = None,
         external_location: Any | None = None,
@@ -413,9 +417,14 @@ class Client(CatalogClientMixin):
                 management.
             transport: Which transport to use. ``"subprocess"`` (default)
                 spawns a local subprocess per worker; ``"http"`` connects to
-                a running worker via ``vgi_rpc.http.http_connect``.
+                a running worker via ``vgi_rpc.http.http_connect``; ``"tcp"``
+                connects to a running worker via ``vgi_rpc.rpc.tcp_connect``
+                (raw Arrow-IPC framing, no auth/encryption — loopback /
+                trusted networks only; use ``Client.from_tcp(...)``).
             base_url: HTTP-only. Base URL of the running worker, e.g.
                 ``"http://127.0.0.1:8765"``.
+            tcp_host: TCP-only. Hostname or IP of the running worker.
+            tcp_port: TCP-only. Port of the running worker.
             bearer_token: HTTP-only. When set, every request carries an
                 ``Authorization: Bearer <token>`` header. Static token
                 support only — no JWT / OAuth flows.
@@ -446,12 +455,21 @@ class Client(CatalogClientMixin):
                 raise ValueError("transport='http' requires base_url")
             if server_path is not None:
                 raise ValueError("server_path is only meaningful for transport='subprocess'")
+        elif transport == "tcp":
+            if tcp_host is None or tcp_port is None:
+                raise ValueError("transport='tcp' requires tcp_host and tcp_port")
+            if server_path is not None:
+                raise ValueError("server_path is only meaningful for transport='subprocess'")
+            if base_url is not None:
+                raise ValueError("base_url is only meaningful for transport='http'")
         else:
             raise ValueError(f"unknown transport {transport!r}")
 
         self.server_path = server_path or ""
         self._transport = transport
         self._base_url = base_url
+        self._tcp_host = tcp_host
+        self._tcp_port = tcp_port
         self._bearer_token = bearer_token
         self._httpx_client = httpx_client
         # True when ``_get_or_create_httpx_client`` constructed the client and
@@ -460,7 +478,7 @@ class Client(CatalogClientMixin):
         self._httpx_client_owned = False
         # Auto-enable pointer-batch resolution for HTTP unless the caller
         # asked for something different. See ``external_location`` docs above.
-        if transport == "http" and external_location is None:
+        if transport in ("http", "tcp") and external_location is None:
             from vgi_rpc.external import ExternalLocationConfig
 
             external_location = ExternalLocationConfig()
@@ -509,6 +527,34 @@ class Client(CatalogClientMixin):
             pool=None,
         )
 
+    @classmethod
+    def from_tcp(
+        cls,
+        host: str,
+        port: int,
+        *,
+        external_location: Any | None = None,
+        worker_limit: int | None = None,
+        attach_opaque_data: bytes | None = None,
+    ) -> Client:
+        """Create a `[`Client`][]` bound to a running TCP VGI worker.
+
+        Connects via ``vgi_rpc.rpc.tcp_connect`` (raw Arrow-IPC framing). The
+        framing carries **no authentication or encryption** — only connect to
+        trusted endpoints on loopback or a trusted network; use
+        ``Client.from_http(...)`` for untrusted networks. Spin up a matching
+        worker with ``vgi-fixture-worker --tcp [HOST:]PORT``.
+        """
+        return cls(
+            transport="tcp",
+            tcp_host=host,
+            tcp_port=port,
+            external_location=external_location,
+            worker_limit=worker_limit,
+            attach_opaque_data=attach_opaque_data,
+            pool=None,
+        )
+
     def _drain_stderr(self, stderr: IO[bytes]) -> None:
         """Background thread that continuously reads stderr.
 
@@ -577,8 +623,40 @@ class Client(CatalogClientMixin):
         """
         if self._transport == "http":
             return self._spawn_http_connection(worker_index)
+        if self._transport == "tcp":
+            return self._spawn_tcp_connection(worker_index)
         return self._spawn_subprocess_connection(worker_index)
 
+    def _spawn_tcp_connection(self, worker_index: int) -> WorkerConnection:
+        """Connect to a running TCP worker via ``vgi_rpc.rpc.tcp_connect``.
+
+        Raw Arrow-IPC framing with no auth/encryption — see ``from_tcp``.
+        Multiple ``worker_index`` values open independent TCP connections to
+        the same ``host:port``.
+        """
+        from vgi_rpc.rpc import tcp_connect
+
+        assert self._tcp_host is not None and self._tcp_port is not None  # enforced in __init__
+        ctx: AbstractContextManager[VgiProtocol] = tcp_connect(
+            VgiProtocol,  # type: ignore[type-abstract]
+            self._tcp_host,
+            self._tcp_port,
+            on_log=self._on_worker_log,
+            external_location=self._external_location,
+        )
+        proxy = ctx.__enter__()
+        _logger.debug(
+            "tcp_connection_opened worker_index=%s host=%s port=%s",
+            worker_index,
+            self._tcp_host,
+            self._tcp_port,
+        )
+        return WorkerConnection(
+            proxy=proxy,
+            worker_index=worker_index,
+            _tcp_ctx=ctx,
+        )
+
     def _spawn_http_connection(self, worker_index: int) -> WorkerConnection:
         """Connect to a remote HTTP worker via ``vgi_rpc.http.http_connect``.
 
@@ -724,6 +802,12 @@ class Client(CatalogClientMixin):
             _logger.debug("http_connection_closed worker_index=%s", worker.worker_index)
             return 0
 
+        if worker._tcp_ctx is not None:
+            # TCP transport — close the RPC proxy (and its socket).
+            worker._tcp_ctx.__exit__(None, None, None)
+            _logger.debug("tcp_connection_closed worker_index=%s", worker.worker_index)
+            return 0
+
         if worker._pool_ctx is not None:
             # Return to pool — pool handles subprocess lifecycle
             worker._pool_ctx.__exit__(None, None, None)
@@ -805,6 +889,8 @@ class Client(CatalogClientMixin):
             id_repr: Any = self._primary.proc.pid
         elif self._primary._http_ctx is not None:
             id_repr = f"http({self._base_url})"
+        elif self._primary._tcp_ctx is not None:
+            id_repr = f"tcp({self._tcp_host}:{self._tcp_port})"
         else:
             id_repr = "pooled"
         _logger.debug("server_started id=%s", id_repr)

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/worker.py

@@ -1276,10 +1276,25 @@ class Worker:
                 "--unix",
                 help="Bind to this AF_UNIX socket path instead of stdin/stdout (mutex with --http).",
             ),
+            # TCP launcher contract — mutually exclusive with --http/--unix.
+            # Accepts ``[HOST:]PORT``; host defaults to loopback (127.0.0.1)
+            # and ``PORT`` may be 0 to auto-select a free port.  After binding
+            # the worker prints TCP:<host>:<port> to stdout and self-shuts-down
+            # after --idle-timeout seconds with zero connected clients. The raw
+            # framing carries no auth/encryption — bind loopback only; use
+            # --http for untrusted networks.
+            tcp: str | None = typer.Option(
+                None,
+                "--tcp",
+                help=(
+                    "Bind a TCP socket ([HOST:]PORT, host defaults to 127.0.0.1, PORT 0 "
+                    "auto-selects) instead of stdin/stdout (mutex with --http/--unix)."
+                ),
+            ),
             idle_timeout: float = typer.Option(
                 300.0,
                 "--idle-timeout",
-                help="Self-shutdown after N seconds idle when serving --unix.",
+                help="Self-shutdown after N seconds idle when serving --unix/--tcp.",
             ),
             http_threads: int | None = typer.Option(  # noqa: B008
                 None,
@@ -1300,8 +1315,8 @@ class Worker:
                 log_format=log_format,
             )
 
-            if http and unix is not None:
-                raise typer.BadParameter("--http and --unix are mutually exclusive")
+            if sum(x for x in (http, unix is not None, tcp is not None)) > 1:
+                raise typer.BadParameter("--http, --unix, and --tcp are mutually exclusive")
 
             if http:
                 from vgi.serve import (
@@ -1358,6 +1373,47 @@ class Worker:
                     idle_timeout=effective_idle,
                     on_bound=_emit,
                 )
+            elif tcp is not None:
+                # TCP launcher path.  Bind to [HOST:]PORT, print
+                # TCP:<host>:<port> on stdout (mirrors run_server's
+                # cross-language discovery contract), idle-shutdown after
+                # idle_timeout seconds.
+                from vgi_rpc.rpc import serve_tcp
+
+                from vgi.serve import _maybe_init_sentry, _resolve_otel_config
+
+                if ":" in tcp:
+                    host_part, _, port_part = tcp.rpartition(":")
+                    tcp_host = host_part or "127.0.0.1"
+                else:
+                    tcp_host, port_part = "127.0.0.1", tcp
+                try:
+                    tcp_port = int(port_part)
+                except ValueError:
+                    raise typer.BadParameter(f"--tcp expects [HOST:]PORT, got {tcp!r}") from None
+
+                _maybe_init_sentry()
+                otel_config = _resolve_otel_config()
+                worker = cls(quiet=quiet, log_level=effective_level)
+                server = RpcServer(cls.protocol_class, worker, server_version=_get_vgi_version())
+                if otel_config is not None:
+                    from vgi_rpc.otel import instrument_server
+
+                    instrument_server(server, otel_config)
+                    worker._vgi_tracer = VgiTracer.create(otel_config)
+                effective_idle = idle_timeout if idle_timeout > 0 else None
+
+                def _emit_tcp(bound_host: str, bound_port: int) -> None:
+                    print(f"TCP:{bound_host}:{bound_port}", flush=True)
+
+                serve_tcp(
+                    server,
+                    tcp_host,
+                    tcp_port,
+                    threaded=True,
+                    idle_timeout=effective_idle,
+                    on_bound=_emit_tcp,
+                )
             else:
                 from vgi.serve import _maybe_init_sentry, _resolve_otel_config
 
@@ -4438,6 +4494,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(

{vgi_python-0.8.5.dist-info → vgi_python-0.8.7.dist-info}/METADATA

@@ -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.dist-info → vgi_python-0.8.7.dist-info}/RECORD

@@ -2,7 +2,7 @@ vgi/__init__.py,sha256=PRtFvXxhHEbY_0KVhyXIbGigZDYKHzMS-4gp0p6IJSQ,3414
 vgi/_duckdb.py,sha256=YB5D7N3Bwg_xP6X8a5QlumtlAovSej1A1Go5XlNGVko,2162
 vgi/_storage_profile.py,sha256=VkTsXojuE0tHEzurmteQSAiL1vI3CZSgYkL6D_h8GvE,5061
 vgi/aggregate_function.py,sha256=vn9TjQEHxAKJl_xzQOzdj5TY_6LplcZjv06JkQMnUyo,25184
-vgi/argument_spec.py,sha256=FFtCNVXhUnEvft51HICOVA7jGJilDW0CHYeyuYexGsg,18142
+vgi/argument_spec.py,sha256=i5VTJSVV5L-gqtyqXOJA_foLMRDo36WcMbcCjvnLyL0,21210
 vgi/arguments.py,sha256=02tIMGIR_cRS73u-bsgpFERxhje-rnTokjBgGsm9pQA,67019
 vgi/auth.py,sha256=3HD2zM-Mt0Ie-_HT5RorpND1OusUw2CPROjPNs7rgbo,1478
 vgi/exceptions.py,sha256=oX_sZc9xGWi7Xf8cJQf89fX19i3ocDEj_V_76GINgBQ,7294
@@ -15,7 +15,7 @@ vgi/logging_config.py,sha256=zQdDuKL-bXwu0n6Pjyqga5SVIyQ25egL2xhV5hbv66k,3100
 vgi/meta_worker.py,sha256=kG5USvnV58S7Wj_RR3W_xM0QlRhaN__m1zwCkA95QOo,29546
 vgi/metadata.py,sha256=VTa625ang6lPgocY4voTOJ7IqET4gsKI4DS07Y53LiM,57914
 vgi/otel.py,sha256=JlUDnk2c0UXSo_j1PJdS67Y--t55sXPg054ADuvHANc,15452
-vgi/protocol.py,sha256=cPTTk6QoawU_hfiRX_Lx_f5x8n9Dyb7BlYcgi9oKt48,116099
+vgi/protocol.py,sha256=-SXv0vIj49wQ3uwwsnnm16yRp-5EweZpKNHwZgtEF5M,116761
 vgi/protocol_version.txt,sha256=WYVJhIUxBN9cNT4vaBoV_HkkdC-aLkaMKa8kjc5FzgM,6
 vgi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 vgi/scalar_function.py,sha256=lPHidmcAo_AtItsGqU4wPJhWfa0r_vAjfY6ZjyaW2BQ,47888
@@ -27,13 +27,13 @@ vgi/table_buffering_function.py,sha256=O5TcIdqk8-YViCQCkb8bOevO-zhe3IoyzLgwXDO3C
 vgi/table_filter_pushdown.py,sha256=zak3AuXLVw51vXew93i81fRReG1H8yr4XxCfRnnISj4,63961
 vgi/table_function.py,sha256=_Ni1deyPaabnQJDQz9CUL4fXy79r_OVyN6ZuWTZ1lMQ,52215
 vgi/table_in_out_function.py,sha256=Ouv02ubP-XsRdByIR0ZSagi6VbZfQ8G1e5QWpqlLqvY,15508
-vgi/worker.py,sha256=SGZsOpER_Aew6CDhyi6I8jchigTJJuL7pyV-E-Rz100,195818
+vgi/worker.py,sha256=t5OKx5mGU91zeV6ErOifeTQmOw16fTOc18jOSDbTDaA,198588
 vgi/_test_fixtures/__init__.py,sha256=xQq-QQLk8USQ6TZHsPiPcZldNNUdcJ2gToXMPGzScLI,444
 vgi/_test_fixtures/attach_options.py,sha256=YtNk1krDdKLnNVtX9yGkgS8XyzdOI0oXtNDbAV73Phg,11091
 vgi/_test_fixtures/bad_enum.py,sha256=lIVemVWTM1JVOHut47Q71Czw-sEiMjfFiyZ15NDaWAk,2910
 vgi/_test_fixtures/bad_protocol.py,sha256=L8kxafWZ-4Sd73F6EpCRo1kWVC-09qzof6OYRXazS_8,2495
 vgi/_test_fixtures/cancellable.py,sha256=hetTRLyT4kkazPNcxAdfzj0pYzEmegMksamJbR0w3Ho,12151
-vgi/_test_fixtures/catalog.py,sha256=CL6E52_vKr_kgGckT0vQO65uUWBSP518Ulfl8nmSey8,28004
+vgi/_test_fixtures/catalog.py,sha256=DuC9r0efwuG-uPdjFFGNMN-Egi2BP9bvDpc1f3uFffM,28106
 vgi/_test_fixtures/http_server.py,sha256=GevITVo61H1Y8K6zWUJj5guB5Y_H6QFfgVtfzRB0EAA,16095
 vgi/_test_fixtures/nest_tensor.py,sha256=UjjW9UwipYG3ehQpZOm4hdzsafMyvVc0ZKJCrqiZTPU,24471
 vgi/_test_fixtures/orchard_catalog.py,sha256=xMknth9FsVs8-y6vQyIZqDfUhJ-susjpMSzOOhaZyxM,1638
@@ -41,7 +41,7 @@ vgi/_test_fixtures/simple_writable.py,sha256=CGmDBUY8kthauEm8eJN2lV72cJ9_TRxOAQC
 vgi/_test_fixtures/table_in_out.py,sha256=7QckA3NJhYAYuSctcwZLul5yOM2V3KWvLuG_33K0B_w,50459
 vgi/_test_fixtures/versioned.py,sha256=Itm-x_Zt9WDwLGT4Dl4VzU5GtFF4HkcaJEqg9ErB8As,5784
 vgi/_test_fixtures/versioned_tables.py,sha256=KRllGGRrwH8JUtqH-tLHT1JL09rKN-EcEYZVeQdbaLs,22112
-vgi/_test_fixtures/worker.py,sha256=5G3shpiPoKWV_DP28UN1LYNp1wIJ2Q-TB8mJ3qok2q4,71230
+vgi/_test_fixtures/worker.py,sha256=m7y5C9meuiOR2iXKnpu7prlq8FX_Zx_b4_Y6b9cNN0I,71676
 vgi/_test_fixtures/accumulate/__init__.py,sha256=4hYT8jqRoVHSjV9TB7v0Z1CMJtdLuPaDWSz4J2fvMDs,868
 vgi/_test_fixtures/accumulate/worker.py,sha256=yal9m-GjKNKUdLOLtwkCyFkeHVv_nnpUjh8amwueT48,30163
 vgi/_test_fixtures/aggregate/__init__.py,sha256=tjCVKdCuHlIAZL7uDi-o_q82oMieXsAyoKExesr-7a0,2156
@@ -98,14 +98,14 @@ vgi/_test_fixtures/writable/worker.py,sha256=nH8KSZqyKv1gqdKn-_OFVh3h02FbyE0NFQ2
 vgi/catalog/__init__.py,sha256=SCpeP2TtPfhWhwaqK5qGmmtHCM2z-EL66OoCkyefy7c,2064
 vgi/catalog/_descriptor_spec.py,sha256=iMqId2fSBqlZ9HU6ct5AkYUAxtRGG_MVTLClDC1WPUs,7673
 vgi/catalog/attach_option.py,sha256=nLGxsfAFR_-NqDrw7v18dtkNNNQIYLr3fuhpVw4XhFc,1739
-vgi/catalog/catalog_interface.py,sha256=aCMSpYczcEb11TmOFdaGTN_F_yOywyR2go1Z6vC_0zY,120231
-vgi/catalog/descriptors.py,sha256=oH-Ld02yQ5oUJb7J9sqGYwhZwaWzZiL3ZPtublmKXzc,39366
+vgi/catalog/catalog_interface.py,sha256=J6eNB-TMIjakKp7wAPKGLubpjM0YwGeUteaYb3PF5dk,121950
+vgi/catalog/descriptors.py,sha256=GrVrFwmyG7GVT4tF3yT7lr-ZcS-qrxFpnFHKw7khTBU,40437
 vgi/catalog/duckdb_statistics.py,sha256=fARQupgq0fD46rDgxDXvdCFsgs-rvCOHhls7WXHmnFY,15615
 vgi/catalog/secret_type.py,sha256=MKtAypBa3xXyr-NC5CHjdX1R00JEnuMtvgboFWC2T9o,3336
 vgi/catalog/setting.py,sha256=06QfgaAR-0BKflIJ0du6PGqA5BPMdrkwr6u7f4nddII,1846
 vgi/catalog/storage.py,sha256=DhngzywbhQUfLF7NjFyiPp4Sw2ovOhcUXAuW3rkBQD8,11935
 vgi/client/__init__.py,sha256=6LPHqlcNFy77apDNXUntgOVLhuXfpJyZd6TI7R7QfbY,2122
-vgi/client/catalog_mixin.py,sha256=PfpdV8KX1R2wkkMG7ffeSkbD9nO7o9ij60a_ApGI45E,45509
+vgi/client/catalog_mixin.py,sha256=fH_D756rzQZHi6UKbeVbWCIScVUqcGw8Dfp8nD36dao,46600
 vgi/client/cli.py,sha256=KfoqIiMXiUNAdYxRp-O6BOi3FA1IsesSBb_XeZGWFSo,22287
 vgi/client/cli_catalog.py,sha256=twjlhHGl7n2mNN4jc7DnDRQr-Zj9KLAF2eATIQnITHQ,5577
 vgi/client/cli_schema.py,sha256=FTkf1moDn_dWFMPDxJqaNFhc2oyrLEutP8xC60EbPIk,7556
@@ -113,7 +113,7 @@ vgi/client/cli_table.py,sha256=hxASTkLZy69z4qoYhpIqrV9ZmZdPLKIzhmHy-hB9qqE,26145
 vgi/client/cli_transaction.py,sha256=TDW0ZrBy8XM_eYSkYk5ewEsnozfzDJOlopd66Fm7OOE,3142
 vgi/client/cli_utils.py,sha256=kilyfxRgFdW63IYQU6xsVls1wIcRjR-ZP63qu0FdXLI,16223
 vgi/client/cli_view.py,sha256=p2wiJAuaEv-8qEgWxiNKgzA9qLdYZ87XCJwkxx5c-YU,8353
-vgi/client/client.py,sha256=M-P3v1Xi5aroTl7Zdtx_tdMT4VjWhTZKiqAog9BDsb4,93582
+vgi/client/client.py,sha256=Pb5qLfydDEnrTW-yCUDSGkerGJesCeHQQbFNTZpxN24,97270
 vgi/http/__init__.py,sha256=hlOwOVcoZqmEKVGk7ganOdr5ryRSpEhLBF9sRD7BkYc,608
 vgi/http/demo_storage.py,sha256=830s-H61thozC3eEuqdnwCpYFfvoJRq9vjyuXa5OURo,8769
 vgi/http/worker_page.py,sha256=Eq70-hPfG2PIuhFjEDMf-BxF7Fdjcb4dN2SploH2jWE,54577
@@ -122,8 +122,8 @@ vgi/transactor/_duckdb_compat.py,sha256=sXVZ9JLKAQyGR1BjWczSwdQEavtr-TcZPoVZZnTr
 vgi/transactor/client.py,sha256=7DTeMksogsw6ANjQjGOPpKYrV76rg4_kGjktMJf54jg,4486
 vgi/transactor/protocol.py,sha256=Mtmll3CdrLFL1B4NY4NZUTO_yi3PT0qhvMQnzapuBWU,4780
 vgi/transactor/server.py,sha256=WpIqjzy2Mebw17Jui4-w7vyGEo9pD-pEZJG-3Ob1Sk8,29705
-vgi_python-0.8.5.dist-info/METADATA,sha256=1dqjWdLcM1MrxAIF8CVYkGA8YCaZF3T5pamDdUYdIj0,24725
-vgi_python-0.8.5.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-vgi_python-0.8.5.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.8.5.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.8.5.dist-info/RECORD,,
+vgi_python-0.8.7.dist-info/METADATA,sha256=tNHKhPZbF3jkRYNokolq5dGV1pj1iLcqN2AedbfdK2I,24725
+vgi_python-0.8.7.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+vgi_python-0.8.7.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
+vgi_python-0.8.7.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
+vgi_python-0.8.7.dist-info/RECORD,,