vgi-python 0.29.3__tar.gz → 0.29.5__tar.gz

{vgi_python-0.29.3 → vgi_python-0.29.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.29.3
+Version: 0.29.5
 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: httpx2>=2.9.1
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.43.0
+Requires-Dist: vgi-rpc>=0.43.2
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'
@@ -181,7 +181,8 @@ Requires-Dist: pytest-ruff; extra == 'dev'
 Requires-Dist: pytest-xdist; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: sqlglot; extra == 'dev'
-Requires-Dist: vgi-rpc[conformance,external,http,oauth,otel,sentry]; extra == 'dev'
+Requires-Dist: vgi-rpc[cli,conformance,external,http,oauth,otel,sentry]; extra == 'dev'
+Requires-Dist: vgi-rpc[cli]; extra == 'dev'
 Requires-Dist: vgi-rpc[http]; extra == 'dev'
 Requires-Dist: vgi-rpc[oauth]; extra == 'dev'
 Requires-Dist: vgi-rpc[otel]; extra == 'dev'
@@ -197,6 +198,8 @@ Provides-Extra: haybarn
 Requires-Dist: haybarn>=1.5.5rc1; extra == 'haybarn'
 Provides-Extra: http
 Requires-Dist: vgi-rpc[http]; extra == 'http'
+Provides-Extra: launch
+Requires-Dist: vgi-rpc[cli]; extra == 'launch'
 Provides-Extra: oauth
 Requires-Dist: vgi-rpc[oauth]; extra == 'oauth'
 Provides-Extra: otel

{vgi_python-0.29.3 → vgi_python-0.29.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.29.3"
+version = "0.29.5"
 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.43.0",
+    "vgi-rpc>=0.43.2",
     "httpx2>=2.9.1",
 ]
 
@@ -52,6 +52,11 @@ dependencies = [
 haybarn = ["haybarn>=1.5.5rc1"]
 duckdb = ["duckdb>=1.5.3"]
 http = ["vgi-rpc[http]"]
+# transport="launch": vgi_rpc.launcher imports filelock unconditionally at
+# module level, which lives behind vgi-rpc's own `cli` extra (alongside
+# typer, already a core dependency here, and httpx2, ditto) rather than in
+# vgi-rpc's core dependency set.
+launch = ["vgi-rpc[cli]"]
 # Alternative HTTP server: granian moves socket I/O and HTTP parsing into Rust,
 # off the GIL. Optional because it is a compiled extension where waitress is
 # pure Python; select it with `vgi-serve --http --server granian`.
@@ -93,8 +98,8 @@ dev = [
     "pytest-ruff",
     "pytest-xdist",
     "ruff",
-    "vgi-python[test-fixtures,test-fixtures-writable,http,oauth,otel,sentry,azure]",
-    "vgi-rpc[conformance,external,http,oauth,otel,sentry]",
+    "vgi-python[test-fixtures,test-fixtures-writable,http,launch,oauth,otel,sentry,azure]",
+    "vgi-rpc[cli,conformance,external,http,oauth,otel,sentry]",
 ]
 [project.scripts]
 vgi-serve = "vgi.serve:main"

vgi_python-0.29.5/tests/table_in_out/test_blended_exchange.py

@@ -0,0 +1,240 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""RPC-level exchange coverage for blended (`RowTransformFunction`) table functions.
+
+`test_blended_metadata.py` covers `resolve_metadata()` in isolation — no worker
+subprocess. This file is the first exchange-level coverage for the blended
+fixtures registered in `vgi/_test_fixtures/table_in_out.py`: it drives them
+through `Client.table_in_out_function(...)`'s new `parent_row_callback`, which
+decodes `vgi_rpc.parent_row#b64` provenance for a 1->N / 1->0 emit (see
+`vgi.protocol._decode_parent_rows`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pyarrow as pa
+import pytest
+
+from tests.conftest import make_schema
+from vgi.arguments import Arguments
+from vgi.client import Client
+from vgi.client.client import ClientError
+
+
+class TestBlendedExplodeProvenance:
+    """`blended_explode`: 1->N fan-out with per-output-row parent_row provenance."""
+
+    def test_parent_row_pairing_is_correct(self, fixture_worker: str) -> None:
+        """Each output row's parent index must point at the input row that produced it.
+
+        Asserting only the final row *set* would pass even for a naive
+        "assume identity" implementation whenever fan-out counts differ
+        across rows -- so this reconstructs the exact expected
+        (parent_row, emitted_value) pairs in emission order and compares.
+        """
+        input_schema = make_schema([pa.field("n", pa.int64())])
+        counts = [0, 1, 3, 2]
+        batch = pa.RecordBatch.from_pydict({"n": counts}, schema=input_schema)
+
+        parent_rows_seen: list[int] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="blended_explode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    parent_row_callback=parent_rows_seen.extend,
+                )
+            )
+
+        assert len(results) == 1
+        out = results[0]
+        i_values = out.column("i").to_pylist()
+
+        assert len(i_values) == sum(counts)
+        assert len(parent_rows_seen) == len(i_values)
+
+        expected_pairs = [(row_idx, k) for row_idx, n in enumerate(counts) for k in range(n)]
+        actual_pairs = list(zip(parent_rows_seen, i_values, strict=True))
+        assert actual_pairs == expected_pairs
+
+    def test_all_rows_filtered_to_empty_result(self, fixture_worker: str) -> None:
+        """n=0 for every input row -> a correctly-schemed, zero-row output."""
+        input_schema = make_schema([pa.field("n", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"n": [0, 0, 0]}, schema=input_schema)
+
+        parent_rows_seen: list[list[int]] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="blended_explode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    parent_row_callback=parent_rows_seen.append,
+                )
+            )
+
+        assert len(results) == 1
+        out = results[0]
+        assert out.num_rows == 0
+        assert out.schema.names == ["i"]
+        assert parent_rows_seen == [[]]
+
+    def test_identity_map_when_row_counts_match(self, fixture_worker: str) -> None:
+        """n=1 for every row -> a 1:1 emit; the identity map is a valid decode.
+
+        `blended_explode` never encodes `vgi_rpc.parent_row` for a 1:1 emit
+        (the C++ reference assumes identity for that case too), so this
+        exercises `_decode_parent_rows`'s absent-metadata branch, not just
+        the explicit-array branch the other tests exercise.
+        """
+        input_schema = make_schema([pa.field("n", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"n": [1, 1, 1]}, schema=input_schema)
+
+        parent_rows_seen: list[int] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="blended_explode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    parent_row_callback=parent_rows_seen.extend,
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("i").to_pylist() == [0, 0, 0]
+        assert parent_rows_seen == [0, 1, 2]
+
+
+class TestHostileProvenance:
+    """`hostile_provenance`: adversarial worker payloads must raise, never corrupt."""
+
+    @pytest.mark.parametrize("mode", ["range", "length", "base64"])
+    def test_malformed_provenance_raises_client_error(
+        self,
+        client_transport: Any,
+        mode: str,
+    ) -> None:
+        """Each hostile mode must raise ClientError on both subprocess and HTTP.
+
+        Symmetry matters here: an asymmetry between transports would mean one
+        parse path validates and the other doesn't -- a security bug, not
+        just an inconsistency.
+        """
+        input_schema = make_schema([pa.field("x", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"x": [1, 2, 3]}, schema=input_schema)
+
+        with client_transport() as client, pytest.raises(ClientError):
+            list(
+                client.table_in_out_function(
+                    function_name="hostile_provenance",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"mode": pa.scalar(mode)}),
+                    parent_row_callback=lambda _rows: None,
+                )
+            )
+
+    def test_no_callback_no_decode_no_raise(self, fixture_worker: str) -> None:
+        """Without `parent_row_callback`, malformed provenance is never even decoded.
+
+        `decode_parent_rows` is derived from `parent_row_callback is not None`
+        -- this is the backward-compat guarantee that an ordinary (non-blended)
+        table-in-out caller, which never passes the callback, is completely
+        unaffected by this feature existing.
+        """
+        input_schema = make_schema([pa.field("x", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"x": [1, 2, 3]}, schema=input_schema)
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="hostile_provenance",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"mode": pa.scalar("range")}),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("hv").to_pylist() == [1, 2, 3]
+
+
+class TestBlendedArityAndVarargs:
+    """Broader coverage once the core provenance mechanism is proven."""
+
+    def test_geo_encode_two_arg_overload(self, fixture_worker: str) -> None:
+        """`geo_encode(lat, lon)` -- the 2-arg overload, identity 1:1 map."""
+        input_schema = make_schema([pa.field("latitude", pa.float64()), pa.field("longitude", pa.float64())])
+        batch = pa.RecordBatch.from_pydict(
+            {"latitude": [52.0, 48.5], "longitude": [13.0, 2.3]},
+            schema=input_schema,
+        )
+
+        parent_rows_seen: list[int] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="geo_encode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"precision": pa.scalar(1)}),
+                    parent_row_callback=parent_rows_seen.extend,
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("geohash").to_pylist() == ["52.0:13.0", "48.5:2.3"]
+        assert parent_rows_seen == [0, 1]
+
+    def test_geo_encode_three_arg_overload(self, fixture_worker: str) -> None:
+        """`geo_encode(lat, lon, alt)` -- same Meta.name, resolved by input arity."""
+        input_schema = make_schema(
+            [
+                pa.field("latitude", pa.float64()),
+                pa.field("longitude", pa.float64()),
+                pa.field("altitude", pa.float64()),
+            ]
+        )
+        batch = pa.RecordBatch.from_pydict(
+            {"latitude": [52.0], "longitude": [13.0], "altitude": [100.0]},
+            schema=input_schema,
+        )
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="geo_encode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"precision": pa.scalar(0)}),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("geohash").to_pylist() == ["52.0:13.0:100.0"]
+
+    def test_row_sum_varargs(self, fixture_worker: str) -> None:
+        """`row_sum(a, b, c)` -- varargs positional input, positionally-named columns."""
+        input_schema = make_schema([pa.field("col0", pa.float64()), pa.field("col1", pa.float64())])
+        batch = pa.RecordBatch.from_pydict({"col0": [1.0, -2.0], "col1": [2.0, -3.0]}, schema=input_schema)
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="row_sum",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"absolute": pa.scalar(True)}),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("row_sum").to_pylist() == [3.0, 5.0]

vgi_python-0.29.5/tests/test_launch_transport.py

@@ -0,0 +1,114 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Round-trip tests for the launcher-managed (``transport="launch"``) transport.
+
+Drives ``vgi._test_fixtures.worker`` (the same fixture module ``test_tcp_transport.py``
+uses) through ``Client.from_launch(...)`` — no separate fixture worker needed, since
+``MetaWorker.serve`` already passes argv through to ``vgi_rpc.rpc.run_server()``, which
+participates in the AF_UNIX launcher path (``--unix PATH --idle-timeout SEC``) the same
+way it participates in the TCP path (``--tcp HOST:PORT``).
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import tempfile
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+
+import pyarrow as pa
+import pytest
+from vgi_rpc.launcher import status_rows
+
+from vgi.arguments import Arguments
+from vgi.client import Client
+
+_WORKER_ARGV = (sys.executable, "-m", "vgi._test_fixtures.worker")
+
+
+@pytest.fixture
+def state_dir() -> Iterator[str]:
+    """Per-test state dir under ``/tmp`` to stay under macOS's 104-byte AF_UNIX limit.
+
+    Mirrors ``vgi-rpc``'s own ``test_launcher.py`` fixture — ``tmp_path`` resolves to a
+    deeply nested path that, concatenated with ``<hash>.sock``, blows past the cap.
+    """
+    d = Path(tempfile.gettempdir()) / f"vgi-launch-test-{uuid.uuid4().hex[:8]}"
+    d.mkdir(mode=0o700)
+    try:
+        yield str(d)
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_launch_round_trip_table_function(state_dir: str) -> None:
+    """A table function streams rows correctly over the launch transport."""
+    with Client.from_launch(_WORKER_ARGV, idle_timeout=10.0, state_dir=state_dir) as client:
+        batches = list(
+            client.table_function(
+                function_name="sequence",
+                schema_name="main",
+                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_launch_round_trip_catalog_listing(state_dir: str) -> None:
+    """Catalog discovery works over the launch transport (catalog_mixin path)."""
+    with Client.from_launch(_WORKER_ARGV, idle_timeout=10.0, state_dir=state_dir) as client:
+        catalogs = client.catalogs()
+
+    assert any(c.name == "example" for c in catalogs)
+
+
+def test_launch_shares_one_worker_across_clients(state_dir: str) -> None:
+    """Two `Client`s with the same worker_argv + state_dir share one warm worker.
+
+    The whole point of the launcher over plain subprocess/TCP: a second client
+    pointing at the same command must reuse the first client's worker rather than
+    spawning its own. Proven by checking exactly one tracked worker exists in the
+    shared state dir after both clients have connected, not by any client-visible
+    process identity (the client has no API for that, by design — it shouldn't need
+    to know or care).
+    """
+    with Client.from_launch(_WORKER_ARGV, idle_timeout=10.0, state_dir=state_dir) as client_a:
+        assert client_a.catalogs()
+        with Client.from_launch(_WORKER_ARGV, idle_timeout=10.0, state_dir=state_dir) as client_b:
+            assert client_b.catalogs()
+            rows = status_rows(Path(state_dir))
+            assert len(rows) == 1, f"expected exactly one shared worker, found {len(rows)}: {rows}"
+            assert rows[0].alive
+
+
+class TestLaunchConstructorValidation:
+    """``transport='launch'`` argument validation."""
+
+    def test_requires_launch_argv(self) -> None:
+        """Launch transport without launch_argv is rejected."""
+        with pytest.raises(ValueError, match="requires a non-empty launch_argv"):
+            Client(transport="launch", pool=None)
+
+    def test_rejects_empty_launch_argv(self) -> None:
+        """An explicitly empty launch_argv is rejected the same as omitting it."""
+        with pytest.raises(ValueError, match="requires a non-empty launch_argv"):
+            Client(transport="launch", launch_argv=(), 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="launch", launch_argv=("x",), 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="launch", launch_argv=("x",), base_url="http://x", pool=None)
+
+    def test_rejects_tcp_host_and_port(self) -> None:
+        """tcp_host/tcp_port are tcp-only."""
+        with pytest.raises(ValueError, match="tcp_host/tcp_port are only meaningful"):
+            Client(transport="launch", launch_argv=("x",), tcp_host="127.0.0.1", tcp_port=1, pool=None)

{vgi_python-0.29.3 → vgi_python-0.29.5}/uv.lock

@@ -714,6 +714,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/da/ef/5790e74a7b39d2c085554f347be22a1882649a29a7a65e9c81bfaf9e8fc6/falcon-4.3.1-py3-none-any.whl", hash = "sha256:5402602d14bc426afc01c388538f2ad402ac4c8c2477415dfe972a2deee17248", size = 332719, upload-time = "2026-06-16T05:31:23.373Z" },
 ]
 
+[[package]]
+name = "filelock"
+version = "3.32.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6d/30/03b03951873a1a0ffc7e8ca0e10c15597b59e8d0e39260704cd2ea087bc4/filelock-3.32.4.tar.gz", hash = "sha256:2bde2e4cf732e0153406d8a7bc80620ecf5e621fe0d25e41143c4e3b4733ff30", size = 222126, upload-time = "2026-08-23T17:37:55.363Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/01/a4/9b63d595d748e3aff8812b65eacc1a2c4bd90b7c2012e08e72373b4835eb/filelock-3.32.4-py3-none-any.whl", hash = "sha256:22e58ca3b1ae3b98993b762d7338367ae64fe50252bf78d59da3bfebcdf1cedd", size = 99864, upload-time = "2026-08-23T17:37:53.913Z" },
+]
+
 [[package]]
 name = "frozenlist"
 version = "1.8.0"
@@ -2560,7 +2569,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.29.2"
+version = "0.29.5"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2591,7 +2600,7 @@ dev = [
     { name = "pytest-xdist" },
     { name = "ruff" },
     { name = "sqlglot" },
-    { name = "vgi-rpc", extra = ["conformance", "external", "http", "oauth", "otel", "sentry"] },
+    { name = "vgi-rpc", extra = ["cli", "conformance", "external", "http", "oauth", "otel", "sentry"] },
 ]
 duckdb = [
     { name = "duckdb" },
@@ -2609,6 +2618,9 @@ haybarn = [
 http = [
     { name = "vgi-rpc", extra = ["http"] },
 ]
+launch = [
+    { name = "vgi-rpc", extra = ["cli"] },
+]
 oauth = [
     { name = "vgi-rpc", extra = ["oauth"] },
 ]
@@ -2672,17 +2684,18 @@ requires-dist = [
     { name = "typer", specifier = ">=0.9" },
     { name = "vgi-fixtures", marker = "extra == 'fixtures'", editable = "packages/vgi-fixtures" },
     { 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 = ["test-fixtures", "test-fixtures-writable", "http", "launch", "oauth", "otel", "sentry", "azure"], marker = "extra == 'dev'" },
     { name = "vgi-python", extras = ["transactor"], marker = "extra == 'test-fixtures-writable'" },
-    { name = "vgi-rpc", specifier = ">=0.43.0" },
-    { name = "vgi-rpc", extras = ["conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
+    { name = "vgi-rpc", specifier = ">=0.43.2" },
+    { name = "vgi-rpc", extras = ["cli"], marker = "extra == 'launch'" },
+    { name = "vgi-rpc", extras = ["cli", "conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'granian'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'http'" },
     { name = "vgi-rpc", extras = ["oauth"], marker = "extra == 'oauth'" },
     { name = "vgi-rpc", extras = ["otel"], marker = "extra == 'otel'" },
     { name = "vgi-rpc", extras = ["sentry"], marker = "extra == 'sentry'" },
 ]
-provides-extras = ["haybarn", "duckdb", "http", "granian", "oauth", "otel", "sentry", "azure", "test-fixtures", "transactor", "fixtures", "test-fixtures-writable", "dev"]
+provides-extras = ["haybarn", "duckdb", "http", "launch", "granian", "oauth", "otel", "sentry", "azure", "test-fixtures", "transactor", "fixtures", "test-fixtures-writable", "dev"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -2703,7 +2716,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.43.1"
+version = "0.43.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2711,12 +2724,17 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/27/a0/b308cc62cde38fe2a7bc7a2c57bbb8e956084dd04134a4b0d805378daf16/vgi_rpc-0.43.1.tar.gz", hash = "sha256:d94a3c2cfcf90e1122b2b7ec23a47912f1b3e2d265267aa6704bd64c3a7f2a55", size = 1145519, upload-time = "2026-08-27T14:51:14.923Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/ce/04/efb99f0fb56535bcba110e6c12448c31b429e0861aae4bc2f7136299cfc2/vgi_rpc-0.43.2.tar.gz", hash = "sha256:6a06437af17442451bfe07186bc472a2efb57e030b0e5b38a28922034a814123", size = 1147340, upload-time = "2026-08-27T18:33:54.608Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/96/f2/15bd8a76ee3534c4d911b0f76c948378db4c175a40ceeb30325e6ab994a6/vgi_rpc-0.43.1-py3-none-any.whl", hash = "sha256:1eecd6c17f06d6fadae332be33998d22cdd01e5caaaae7889b747f0c1eaac498", size = 526753, upload-time = "2026-08-27T14:51:12.975Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/b9/33cdb4fe27ef3893e1cded63f396af8bc517e390615f34db6f4bd227ef4c/vgi_rpc-0.43.2-py3-none-any.whl", hash = "sha256:b112ab76828367176a41f1b9a4ceeaba8979629e4e5972f64bf769c94b3e36a4", size = 528134, upload-time = "2026-08-27T18:33:52.829Z" },
 ]
 
 [package.optional-dependencies]
+cli = [
+    { name = "filelock" },
+    { name = "httpx2" },
+    { name = "typer" },
+]
 conformance = [
     { name = "jsonschema" },
     { name = "psutil" },

{vgi_python-0.29.3 → vgi_python-0.29.5}/vgi/client/catalog_mixin.py

@@ -100,9 +100,11 @@ class CatalogClientMixin:
     non-DuckDB use case this mixin supports.
 
     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).
+    http, tcp, or launch), ``_base_url`` (HTTP base URL), ``_tcp_host`` /
+    ``_tcp_port`` (TCP endpoint), ``_launch_argv`` / ``_launch_idle_timeout`` /
+    ``_launch_state_dir`` / ``_launch_socket_path`` (launcher worker
+    identity + lifecycle), and ``_get_or_create_httpx_client()`` (shared
+    HTTP client factory).
 
     Attributes:
         server_path: Worker command used for subprocess transport — a string to
@@ -111,10 +113,14 @@ class CatalogClientMixin:
 
     # Type hints for attributes expected from Client
     server_path: str | Sequence[str]
-    _transport: Literal["subprocess", "http", "tcp"]
+    _transport: Literal["subprocess", "http", "tcp", "launch"]
     _base_url: str | None
     _tcp_host: str | None
     _tcp_port: int | None
+    _launch_argv: tuple[str, ...] | None
+    _launch_idle_timeout: float
+    _launch_state_dir: str | None
+    _launch_socket_path: str | None
     _external_location: Any | None
 
     def _worker_argv(self) -> list[str]:
@@ -144,6 +150,11 @@ class CatalogClientMixin:
         ``Client._get_or_create_httpx_client`` so auth headers and
         connection pooling are consistent.
 
+        Launch: opens a short-lived ``resolve_and_connect`` session per call
+        against the launcher-managed shared worker — same warm-worker sharing
+        as exchange-mode calls (``Client._spawn_launch_connection``), just a
+        fresh connection to it per catalog RPC rather than one held open.
+
         Worker errors are caught and re-raised as ``CatalogClientError``.
 
         Yields:
@@ -173,6 +184,22 @@ class CatalogClientMixin:
                     external_location=getattr(self, "_external_location", None),
                 ) as proxy:
                     yield proxy
+            elif transport == "launch":
+                from vgi_rpc.launcher import LaunchConfig, resolve_and_connect
+
+                assert self._launch_argv is not None
+                config = LaunchConfig(
+                    worker_argv=self._launch_argv,
+                    socket_path=self._launch_socket_path,
+                    idle_timeout=self._launch_idle_timeout,
+                    state_dir=self._launch_state_dir,
+                )
+                with resolve_and_connect(
+                    VgiProtocol,  # type: ignore[type-abstract]
+                    config,
+                    external_location=getattr(self, "_external_location", None),
+                ) as proxy:
+                    yield proxy
             else:
                 cmd = self._worker_argv()
                 with _catalog_pool.connect(VgiProtocol, cmd) as proxy:  # type: ignore[type-abstract]