Move LLM examples out, drive mypy to zero, sweep schema_utils

- Relocated vgi/examples/{summarize,distill}.py to ~/Development/vgi-anthropic/
  and dropped the [llm] extra; they were Anthropic-API experiments and the
  bulk of the prior mypy noise.
- Added vgi/transactor/_duckdb_compat.py — Protocol+cast shim so the VGI
  fork's DuckDBPyConnection.subcursor() type-checks without polluting the
  upstream stubs.
- Drove mypy vgi/ to zero errors: typed heterogeneous Field/Array lists
  with Any (matching house style in schema_utils/arguments), tightened
  None narrowings (mask: ChunkedArray[BooleanScalar] | BooleanArray),
  fixed varargs annotations in aggregate.py to list[pa.Array[Any]],
  added type:ignore[override] on the partial schema_contents override
  in versioned_tables.
- Swept ~25 pa.schema([pa.field(...), ...]) literals to vgi.schema_utils
  schema(name=type, ...) — eliminates 7 # type: ignore[arg-type]
  comments and ~150 lines of boilerplate. Field-level metadata and
  comprehension-built schemas use the (type, metadata) tuple and
  schema(mapping) forms respectively. Skipped pa.schema([]) empty,
  pa.schema([field]) with dynamic name, and the one transactor site
  that combines a field prepend, schema spread, and schema-level
  metadata.
- DRY follow-ups: shared _ON_CANCEL_CAVEATS docstring constant between
  TableFunctionGenerator and TableInOutGenerator; _append_cancel_probe
  helper in cancellable.py; start_http_worker helper in
  tests/_http_fixtures.py used by both http_worker and client_transport
  fixtures.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: rustyconover

pyproject.toml

@@ -28,9 +28,6 @@ azure = [
     "pymssql>=2.3.0",
     "azure-identity>=1.16.0",
 ]
-llm = [
-    "anthropic>=0.40.0",
-]
 dev = [
     "mypy",
     "pyarrow-stubs",

tests/_http_fixtures.py

@@ -0,0 +1,97 @@
+"""Shared helpers for spawning ``vgi-example-http`` as a subprocess.
+
+Lifted from ``tests/test_http_demo_storage.py`` so that conformance tests and
+other HTTP-dependent tests can reuse a single lifecycle.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import sys
+import time
+from collections.abc import Iterator, Sequence
+from contextlib import ExitStack, contextmanager
+
+
+def free_port() -> int:
+    """Allocate an available localhost TCP port."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return int(s.getsockname()[1])
+
+
+@contextmanager
+def run_example_http_server(
+    *,
+    port: int,
+    extra_args: Sequence[str] = (),
+    env: dict[str, str] | None = None,
+) -> Iterator[None]:
+    """Run ``vgi-example-http`` in a subprocess on ``port``.
+
+    ``extra_args`` are appended verbatim — e.g. ``("--demo-storage",
+    "--externalize-threshold-bytes", "4096")``.
+    """
+    cmd = [
+        sys.executable,
+        "-m",
+        "vgi.examples.http_server",
+        "--host",
+        "127.0.0.1",
+        "--port",
+        str(port),
+        *extra_args,
+    ]
+    proc_env = os.environ.copy()
+    if env is not None:
+        proc_env.update(env)
+    proc = subprocess.Popen(
+        cmd,
+        env=proc_env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    try:
+        yield
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=5)
+
+        if proc.returncode not in (0, -15):
+            stderr = proc.stderr.read() if proc.stderr is not None else ""
+            raise RuntimeError(f"example HTTP worker exited with code {proc.returncode}: {stderr}")
+
+
+def start_http_worker(
+    stack: ExitStack,
+    *,
+    extra_args: Sequence[str] = (),
+    env: dict[str, str] | None = None,
+) -> str:
+    """Allocate a port, start ``vgi-example-http`` under ``stack``, return base URL."""
+    port = free_port()
+    base_url = f"http://127.0.0.1:{port}"
+    stack.enter_context(run_example_http_server(port=port, extra_args=tuple(extra_args), env=env))
+    wait_for_http_server(base_url)
+    return base_url
+
+
+def wait_for_http_server(base_url: str, timeout: float = 30.0) -> None:
+    """Block until the HTTP server responds to a capabilities probe."""
+    from vgi_rpc.http import http_capabilities
+
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            http_capabilities(base_url=base_url)
+            return
+        except Exception:
+            time.sleep(0.25)
+    raise TimeoutError(f"Timed out waiting for HTTP server at {base_url}")

tests/conftest.py

@@ -74,6 +74,91 @@ def example_worker() -> str:
     return "vgi-example-worker"
 
 
+@pytest.fixture
+def http_worker() -> Any:
+    """Start ``vgi-example-http`` on a free port, yield its base URL, tear it down.
+
+    Usage::
+
+        def test_something(http_worker):
+            base_url = http_worker()                       # defaults
+            base_url = http_worker(extra_args=[...])       # pass flags
+
+    Implemented as a factory so individual tests can request different server
+    flags (e.g. ``--demo-storage``) without proliferating fixtures.
+    """
+    from contextlib import ExitStack
+
+    from tests._http_fixtures import start_http_worker
+
+    pytest.importorskip("vgi_rpc.http")
+
+    stack = ExitStack()
+
+    def _start(*, extra_args: list[str] | None = None, env: dict[str, str] | None = None) -> str:
+        return start_http_worker(stack, extra_args=tuple(extra_args or ()), env=env)
+
+    try:
+        yield _start
+    finally:
+        stack.close()
+
+
+# Keys used to identify transport modes in conformance tests. Keeping the
+# literal values here (rather than inside the fixture) makes it easy for
+# individual tests to opt out with ``@pytest.mark.parametrize("client_transport",
+# ["subprocess-pooled"], indirect=True)``.
+_CLIENT_TRANSPORT_MODES = ["subprocess-pooled", "subprocess-direct", "http"]
+
+
+@pytest.fixture(params=_CLIENT_TRANSPORT_MODES)
+def client_transport(request: pytest.FixtureRequest, example_worker: str) -> Any:
+    """Parametrized factory that builds a configured ``Client`` for each transport.
+
+    Yields a callable ``make_client()`` -> ``Client``. Callers must enter the
+    returned client as a context manager.
+
+    Modes:
+        subprocess-pooled: Pool-backed subprocess (the default path).
+        subprocess-direct: ``pool=None`` — direct Popen management.
+        http: ``Client.from_http(base_url)`` backed by a per-test
+            ``vgi-example-http`` subprocess. Skips if the HTTP transport
+            isn't wired yet.
+    """
+    from vgi.client.client import _HTTP_TRANSPORT_READY, Client, _default_pool
+
+    mode = request.param
+
+    http_base_url: str | None = None
+    http_stack: Any | None = None
+
+    def _make() -> Client:
+        nonlocal http_base_url, http_stack
+        if mode == "subprocess-pooled":
+            return Client(example_worker, pool=_default_pool)
+        if mode == "subprocess-direct":
+            return Client(example_worker, pool=None)
+        if mode == "http":
+            if not _HTTP_TRANSPORT_READY:
+                pytest.skip("Client HTTP transport arrives in Phase 2 of whimsical-mccarthy plan")
+            pytest.importorskip("vgi_rpc.http")
+            from contextlib import ExitStack
+
+            from tests._http_fixtures import start_http_worker
+
+            if http_base_url is None:
+                http_stack = ExitStack()
+                http_base_url = start_http_worker(http_stack)
+            return Client.from_http(http_base_url)
+        raise AssertionError(f"unknown transport mode {mode!r}")
+
+    try:
+        yield _make
+    finally:
+        if http_stack is not None:
+            http_stack.close()
+
+
 @pytest.fixture
 def simple_batches() -> list[pa.RecordBatch]:
     """Create simple test batches with integer and string columns."""