vgi-python 0.8.0__py3-none-any.whl

vgi_python-0.8.0.dist-info/METADATA

@@ -0,0 +1,735 @@
+Metadata-Version: 2.4
+Name: vgi-python
+Version: 0.8.0
+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
+Project-URL: Documentation, https://github.com/Query-farm/vgi-python/tree/main/docs
+Project-URL: Issues, https://github.com/Query-farm/vgi-python/issues
+Author-email: Rusty Conover <rusty@query.farm>
+Maintainer-email: Query Farm LLC <hello@query.farm>
+License: Query Farm Source-Available License, Version 1.0
+        
+        Copyright (c) 2025, 2026 Query Farm LLC. All rights reserved.
+        
+        ## 1. Definitions
+        
+        "Licensor" means Query Farm LLC (http://query.farm, hello@query.farm) and its
+        affiliates under common control.
+        
+        "VGI" means the Vector Gateway Interface, the DuckDB extension technology developed
+        by the Licensor, also referred to by the Licensor as its "Hyperfederation" database
+        technology.
+        
+        "Licensed Work" means VGI, including its source code, object code, and any
+        documentation distributed with it, in each version made available by the Licensor
+        under this License.
+        
+        "You" (or "Your") means the individual or legal entity exercising rights under this
+        License, together with all affiliates under common control with that entity.
+        
+        "Production Use" means any use of the Licensed Work other than for development,
+        testing, evaluation, experimentation, or other non-production purposes.
+        
+        "Hyperfederation Services" means services relating to the federation, gateway,
+        integration, querying, or interoperation of data sources using VGI or
+        functionally equivalent technology, including services that expose, broker, or
+        provide access to such federated or gateway capabilities.
+        
+        "Commercial Marketplace" means any platform, exchange, or intermediary service,
+        whether or not operated for a fee, that connects providers and consumers of
+        Hyperfederation Services, or that facilitates the offering, discovery, exchange,
+        sale, or licensing of Hyperfederation Services among third parties.
+        
+        "Competing Offering" means a product or service that You make available to third
+        parties, on a paid basis (including through paid support, subscription, or hosting
+        arrangements), whose capabilities significantly overlap with those of the Licensor's
+        version(s) of the Licensed Work.
+        
+        ## 2. Grant of Rights
+        
+        Subject to the terms and limitations of this License, the Licensor grants You a
+        worldwide, royalty-free, non-exclusive license to:
+        
+        (a) use, copy, and run the Licensed Work for any non-production purpose;
+        
+        (b) modify the Licensed Work and create derivative works of it;
+        
+        (c) redistribute the Licensed Work and Your derivative works, provided You comply
+        with Section 5; and
+        
+        (d) make Production Use of the Licensed Work, except where such use is restricted by
+        Section 3 or reserved to the Licensor by Section 4.
+        
+        ## 3. Production Use Conditions
+        
+        The grant of Production Use in Section 2(d) does not extend to, and You may not
+        without a separate commercial license from the Licensor:
+        
+        (a) provide a Competing Offering to third parties; or
+        
+        (b) offer the Licensed Work, or any derivative work of it, to third parties on a
+        hosted, embedded, or as-a-service basis where doing so competes with the Licensor's
+        commercial interests in the Licensed Work.
+        
+        "Embedded" includes incorporating the source or object code of the Licensed Work
+        into a Competing Offering, and packaging a Competing Offering such that the Licensed
+        Work must be accessed or downloaded for that offering to function.
+        
+        Hosting or using the Licensed Work for Your own internal purposes is not a Competing
+        Offering and is permitted, including across Your affiliates under common control.
+        
+        ## 4. Reserved Rights
+        
+        Notwithstanding any other provision of this License, the Licensor reserves to itself
+        the exclusive right to build, operate, offer, or authorize a Commercial Marketplace
+        that incorporates, integrates, is built upon, or otherwise uses the Licensed Work.
+        
+        This License grants You no right to construct, operate, or enable a Commercial
+        Marketplace using the Licensed Work, whether on a commercial or non-commercial basis,
+        and any such use requires a separate written agreement with the Licensor.
+        
+        ## 5. Redistribution
+        
+        If You redistribute the Licensed Work or any derivative work of it, in original or
+        modified form, You must:
+        
+        (a) include a complete, unmodified copy of this License with each copy; and
+        
+        (b) cause any recipient to receive the Licensed Work subject to the terms of this
+        License.
+        
+        The conditions in Sections 3 and 4 apply to every recipient of the Licensed Work,
+        whether received directly from the Licensor or through a third party.
+        
+        ## 6. Conversion to Open Source
+        
+        For each version of the Licensed Work, on the tenth anniversary of the date the
+        Licensor first made that version publicly available (the "Change Date" for that
+        version), the Licensor additionally grants You the right to use that version under
+        the terms of the Apache License, Version 2.0, and on and after that version's Change
+        Date the restrictions in Sections 3 and 4 no longer apply to that version.
+        
+        This License applies separately to each version of the Licensed Work, and the Change
+        Date may differ between versions.
+        
+        ## 7. Commercial Licensing
+        
+        If Your intended use is not permitted under this License, You may obtain a separate
+        commercial license from the Licensor by contacting hello@query.farm. Absent such a
+        license, You must refrain from the restricted use.
+        
+        ## 8. Trademarks
+        
+        This License does not grant You any right to use the names, trademarks, service
+        marks, or logos of the Licensor, including "Vector Gateway Interface," "VGI," and
+        "Hyperfederation," except as required for reasonable and customary use in describing
+        the origin of the Licensed Work.
+        
+        ## 9. Termination
+        
+        Any use of the Licensed Work in violation of this License automatically terminates
+        Your rights under this License for the current and all other versions of the Licensed
+        Work. Your rights may be reinstated only by a writing signed by the Licensor.
+        
+        ## 10. Disclaimer of Warranty and Limitation of Liability
+        
+        TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+        AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED,
+        INCLUDING WITHOUT LIMITATION ANY WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS
+        FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE.
+        
+        TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL THE LICENSOR BE
+        LIABLE TO YOU FOR ANY DAMAGES ARISING OUT OF OR RELATING TO THIS LICENSE OR THE USE
+        OF THE LICENSED WORK, WHETHER IN CONTRACT, TORT, OR OTHERWISE.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: click
+Requires-Dist: httpx>=0.24
+Requires-Dist: platformdirs
+Requires-Dist: pyarrow
+Requires-Dist: typer>=0.9
+Requires-Dist: vgi-rpc>=0.20.0
+Provides-Extra: azure
+Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
+Requires-Dist: pymssql>=2.3.0; extra == 'azure'
+Provides-Extra: dev
+Requires-Dist: azure-identity>=1.16.0; extra == 'dev'
+Requires-Dist: duckdb>=1.5.3; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: numpy>=2.4.1; extra == 'dev'
+Requires-Dist: pyarrow-stubs; extra == 'dev'
+Requires-Dist: pymssql>=2.3.0; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-examples; extra == 'dev'
+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[http]; extra == 'dev'
+Requires-Dist: vgi-rpc[oauth]; extra == 'dev'
+Requires-Dist: vgi-rpc[otel]; extra == 'dev'
+Requires-Dist: vgi-rpc[sentry]; extra == 'dev'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=1.5.3; extra == 'duckdb'
+Provides-Extra: fixtures
+Requires-Dist: vgi-fixtures; extra == 'fixtures'
+Provides-Extra: haybarn
+Requires-Dist: haybarn>=1.5.3rc10; extra == 'haybarn'
+Provides-Extra: http
+Requires-Dist: vgi-rpc[http]; extra == 'http'
+Provides-Extra: oauth
+Requires-Dist: vgi-rpc[oauth]; extra == 'oauth'
+Provides-Extra: otel
+Requires-Dist: vgi-rpc[otel]; extra == 'otel'
+Provides-Extra: sentry
+Requires-Dist: vgi-rpc[sentry]; extra == 'sentry'
+Provides-Extra: test-fixtures
+Requires-Dist: numpy>=2.4.1; extra == 'test-fixtures'
+Provides-Extra: test-fixtures-writable
+Requires-Dist: numpy>=2.4.1; extra == 'test-fixtures-writable'
+Requires-Dist: sqlglot; extra == 'test-fixtures-writable'
+Provides-Extra: transactor
+Requires-Dist: sqlglot; extra == 'transactor'
+Description-Content-Type: text/markdown
+
+# VGI (Vector Gateway Interface)
+
+<p align="center">
+  <img src="docs/vgi-logo.png" alt="VGI Logo" width="400">
+</p>
+
+<p align="center">
+  <strong>Apache Arrow-based protocol for extending DuckDB using any language.</strong><br/>
+  <strong>No C++/C/Zig/Rust or compilation/linking required (unless you want to).</strong>
+</p>
+
+<p align="center">
+  Created by <a href="https://query.farm">Query.Farm</a>
+</p>
+
+---
+
+## See It in Action
+
+```python
+# my_worker.py
+from typing import Annotated
+from vgi import ScalarFunction, Param, Returns, Worker
+import pyarrow as pa
+import pyarrow.compute as pc
+
+class Greeting(ScalarFunction):
+    """Generate a greeting for each name."""
+
+    @classmethod
+    def compute(
+        cls,
+        name: Annotated[pa.StringArray, Param(doc="Column containing names")],
+    ) -> Annotated[pa.StringArray, Returns()]:
+        return pc.binary_join_element_wise("Hello, ", name, "!")
+
+class MyWorker(Worker):
+    functions = [Greeting]
+
+if __name__ == "__main__":
+    MyWorker().run()
+```
+
+```sql
+-- First time only.
+INSTALL vgi FROM COMMUNITY;
+LOAD vgi;
+ATTACH 'my_worker' (TYPE 'vgi', LOCATION './my_worker.py');
+
+SELECT greeting(name) FROM users;
+-- "Hello, Alice!"
+-- "Hello, Bob!"
+```
+
+Or you can launch the DuckDB CLI with
+
+`duckdb vgi:my_worker.py` to start a new session with the functions you just added.
+
+That's it. No C++ compilation, no extension versioning, no complex build process. Just a Python script that DuckDB can call.
+
+---
+
+## Installation
+
+```bash
+pip install vgi
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add vgi
+```
+
+---
+
+## Why VGI?
+
+VGI lets you extend DuckDB with Python functions that run in separate processes, communicating via Apache Arrow IPC. This means:
+
+| Traditional Extensions | VGI Workers |
+|----------------------|-------------|
+| C/C++ compilation required | Any language but first Python and Typescript and Go |
+| Tied to DuckDB version | Version independent |
+| Complex build/release cycle | Ship a script or executable |
+| Runs in-process | Process isolation |
+| Single-threaded | Parallel workers |
+
+**Use cases:**
+- Call REST APIs or external services from SQL
+- Run ML inference (PyTorch, scikit-learn, etc.)
+- Process data with Python libraries (pandas, numpy)
+- Build custom ETL transforms
+- Create domain-specific functions for your team
+- Expose external data sources as queryable tables and views
+
+---
+
+## Quick Start
+
+### Step 1: Create a Worker
+
+A worker is a Python script that defines one or more functions:
+
+```python
+#!/usr/bin/env python
+# my_worker.py
+from typing import Annotated
+import pyarrow as pa
+import pyarrow.compute as pc
+from vgi import ScalarFunction, Param, Returns, Worker
+
+
+class UpperCase(ScalarFunction):
+    """Convert string values to uppercase."""
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.StringArray, Param(doc="String value to uppercase")],
+    ) -> Annotated[pa.StringArray, Returns()]:
+        return pc.utf8_upper(value)
+
+
+class MyWorker(Worker):
+    catalog_name = "my_funcs"
+    functions = [UpperCase]
+
+
+if __name__ == "__main__":
+    MyWorker().run()
+```
+
+### Step 2: Use from DuckDB
+
+```sql
+-- Attach the worker as a catalog
+ATTACH 'my_funcs' (TYPE 'vgi', LOCATION './my_worker.py');
+
+-- Call your function
+SELECT upper_case(name) FROM users;
+
+-- Use in complex queries
+SELECT id, upper_case(status) as status
+FROM orders
+WHERE created_at > '2024-01-01';
+```
+
+### Step 3: There is no step 3
+
+Your function is now available in DuckDB. Ship the Python script to your team, and they can use it immediately.
+
+---
+
+## Going Further: Type-Safe Arguments
+
+For production use, you'll want type validation. Use `Param` with `type_bound` to ensure columns have the correct type:
+
+```python
+from typing import Annotated
+from vgi import ScalarFunction, Param, Returns, Worker
+import pyarrow as pa
+import pyarrow.compute as pc
+
+
+class AddValues(ScalarFunction):
+    """Add two integer values together."""
+
+    @classmethod
+    def compute(
+        cls,
+        left: Annotated[pa.Int64Array, Param(type_bound=pa.types.is_integer, doc="First integer value")],
+        right: Annotated[pa.Int64Array, Param(type_bound=pa.types.is_integer, doc="Second integer value")],
+    ) -> Annotated[pa.Int64Array, Returns()]:
+        return pc.add(left, right)
+```
+
+```sql
+SELECT add_values(price, tax) as total FROM orders;
+
+-- This would fail at bind time with a clear error:
+-- SELECT add_values(name, price) FROM orders;
+-- Error: Column 'name' has type string, expected integer
+```
+
+Key features of the `Param`/`Returns` API:
+- Types are inferred from PyArrow array annotations (`pa.Int64Array` -> `pa.int64()`)
+- `type_bound` validates the column's Arrow type at bind time
+- `ConstParam` receives scalar values (not columns) from SQL arguments
+- `Returns` declares the output type
+
+---
+
+## Function Types
+
+VGI supports three function types:
+
+| Type | Base Class | SQL Pattern | Use Case |
+|------|------------|-------------|----------|
+| **Scalar** | `ScalarFunction` | `SELECT func(col) FROM t` | Per-row transforms (1:1) |
+| **Table** | `TableFunctionGenerator` | `SELECT * FROM func(args)` | Generate data |
+| **Table-In-Out** | `TableInOutFunction` | `SELECT * FROM func((SELECT ...))` | Aggregation, filtering |
+
+### Scalar Functions
+
+Transform each row independently. Output has the same number of rows as input.
+
+```python
+class Double(ScalarFunction):
+    """Double an integer value."""
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.Int64Array, Param(doc="Value to double")],
+    ) -> Annotated[pa.Int64Array, Returns()]:
+        return pc.multiply(value, 2)
+```
+
+### Table Functions
+
+Generate output data from arguments (no input table). Each call to `process()` emits
+a batch via `out.emit()` or signals completion via `out.finish()`.
+
+```python
+from dataclasses import dataclass
+from typing import Annotated, ClassVar
+import pyarrow as pa
+from vgi import TableFunctionGenerator, Arg
+from vgi.table_function import ProcessParams, OutputCollector
+
+
+@dataclass
+class CounterState:
+    remaining: int
+    current: int = 0
+
+
+class Counter(TableFunctionGenerator):
+    """Generate a sequence of integers."""
+
+    count: Annotated[int, Arg(0, doc="Number of rows to generate")]
+    FIXED_SCHEMA: ClassVar[pa.Schema] = pa.schema([("n", pa.int64())])
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams) -> CounterState:
+        return CounterState(remaining=params.args.count)
+
+    @classmethod
+    def process(cls, params: ProcessParams, state: CounterState, out: OutputCollector) -> None:
+        if state.remaining <= 0:
+            out.finish()
+            return
+        batch_size = min(state.remaining, 1000)
+        values = list(range(state.current, state.current + batch_size))
+        out.emit(pa.RecordBatch.from_pydict({"n": values}, schema=params.output_schema))
+        state.current += batch_size
+        state.remaining -= batch_size
+```
+
+### Table-In-Out Functions
+
+Transform or aggregate input data. Override `transform()` for per-batch processing
+and `finish()` for final output after all input is consumed.
+
+```python
+import pyarrow as pa
+import pyarrow.compute as pc
+from vgi import TableInOutFunction
+
+
+class FilterPositive(TableInOutFunction):
+    """Keep only rows where all numeric columns are positive."""
+
+    @property
+    def output_schema(self) -> pa.Schema:
+        return self.input_schema
+
+    def transform(self, batch: pa.RecordBatch) -> pa.RecordBatch:
+        mask = None
+        for i, field in enumerate(batch.schema):
+            if pa.types.is_integer(field.type) or pa.types.is_floating(field.type):
+                col_mask = pc.greater(batch.column(i), 0)
+                mask = col_mask if mask is None else pc.and_(mask, col_mask)
+        if mask is not None:
+            return pc.filter(batch, mask)
+        return batch
+```
+
+---
+
+## Beyond Functions: Full Catalog Support
+
+VGI workers can expose more than just functions. A worker can provide a complete database catalog with:
+
+- **Schemas** - Organize objects into namespaces
+- **Tables** - Expose external data as queryable tables
+- **Views** - Define SQL views over your data
+- **Functions** - Scalar, table, and table-in-out functions
+
+```sql
+ATTACH 'external_db' (TYPE 'vgi', LOCATION './my_catalog_worker.py');
+
+-- Query tables from the attached catalog
+SELECT * FROM external_db.main.users;
+
+-- Use views
+SELECT * FROM external_db.analytics.daily_summary;
+
+-- Call functions
+SELECT external_db.main.transform(col) FROM my_table;
+```
+
+This enables VGI workers to act as bridges to external systems—databases, APIs, file systems—presenting them as native DuckDB catalogs.
+
+See [Catalog Interface](docs/catalog-interface.md) for implementation details.
+
+---
+
+## Parallel Execution
+
+Functions can run across multiple worker processes. The client automatically
+distributes input batches round-robin across workers and collects results.
+
+See [Function API Reference](docs/generator-api.md) for advanced patterns like distributed aggregation.
+
+---
+
+## Error Handling
+
+Errors in your functions propagate to DuckDB with clear messages:
+
+```python test="skip"
+@classmethod
+def compute(cls, value: Annotated[pa.Int64Array, Param()]) -> Annotated[pa.Int64Array, Returns()]:
+    raise ValueError("Something went wrong")
+```
+
+```sql
+SELECT my_func(col) FROM my_table;
+-- Error: Something went wrong
+```
+
+Type bound violations are caught at bind time (before processing starts):
+
+```sql
+SELECT add_values(name, price) FROM orders;
+-- Error: Argument 'left': Column 'name' has type string,
+--        but type bound requires: is_integer
+```
+
+### Debugging Worker Failures
+
+When a worker fails, the Python traceback is written to stderr. By default, the client captures this stderr and includes it in the error message (last 50 lines), so you get the full context:
+
+```
+ClientError: Worker Exception: function 'my_func' raised ValueError
+
+Worker stderr:
+Traceback (most recent call last):
+  File "my_worker.py", line 42, in compute
+    ...
+ValueError: Something went wrong
+```
+
+For real-time debugging, set `VGI_WORKER_DEBUG=1` to stream worker logs directly to your terminal and enable DEBUG-level logging:
+
+```bash
+VGI_WORKER_DEBUG=1 python my_script.py
+```
+
+This is especially useful when integrating from C++ or other clients where stderr might otherwise be lost.
+
+---
+
+## Testing Your Functions
+
+Use the VGI client for integration tests:
+
+```python
+from vgi.client import Client
+from vgi import Arguments
+import pyarrow as pa
+
+batch = pa.RecordBatch.from_pydict({"name": ["alice", "bob"]})
+
+with Client("./my_worker.py") as client:
+    results = list(client.scalar_function(
+        function_name="upper_case",
+        input=iter([batch]),
+        arguments=Arguments(positional=[pa.scalar("name")]),
+    ))
+
+assert results[0]["result"].to_pylist() == ["ALICE", "BOB"]
+```
+
+---
+
+## Protocol Overview
+
+VGI uses `vgi_rpc`, an Apache Arrow IPC-based RPC framework, for all
+client-worker communication over stdin/stdout pipes:
+
+```
+Client                              Worker
+  │                                   │
+  │──── bind(request) ──────────────▶ │  Function name, args, input schema
+  │◀─── BindResponse ────────────────  │  Output schema, opaque data
+  │                                   │
+  │──── init(request) ──────────────▶ │  Start processing stream
+  │◀─── Stream header ───────────────  │  execution_id, max_workers
+  │                                   │
+  │──── exchange(batch1) ───────────▶ │
+  │◀─── output batch 1 ──────────────  │  transform(batch)
+  │         ...                       │
+  │──── [stream close] ─────────────▶ │  Signal end of input
+  │                                   │
+  │──── init(phase=FINALIZE) ───────▶ │  Start finalize stream
+  │◀─── final output batches ────────  │  finish() results
+  └───────────────────────────────────┘
+```
+
+---
+
+## External Batch Offloading (Demo Storage)
+
+When record batches are too large for HTTP request/response bodies, VGI supports
+externalizing them to blob storage. The server replaces oversized batches with
+pointer batches containing a URL, and the client transparently fetches the data.
+
+The example HTTP server includes a built-in demo blob store for testing this
+without S3 or any cloud infrastructure:
+
+```bash
+# Start with demo storage (4 KiB threshold for testing)
+vgi-fixture-http --demo-storage --externalize-threshold-bytes 4096
+
+# With zstd compression
+vgi-fixture-http --demo-storage --externalize-threshold-bytes 4096 --externalize-compression zstd
+```
+
+When `--demo-storage` is enabled:
+- Batches exceeding `--externalize-threshold-bytes` are stored in-memory and
+  served from `/__blobs__/{id}` endpoints on the same server
+- Clients can request upload URLs for large inputs via the `__upload_url__` endpoint
+- The server advertises `VGI-Max-Request-Bytes` and rejects oversized requests with 413
+
+For production use, implement the `ExternalStorage` protocol from `vgi_rpc` against
+your cloud storage (S3, GCS, etc.). The example server also supports S3 via `--s3-bucket`.
+
+---
+
+## Documentation
+
+- [Function Lifecycle](docs/lifecycle.md) - Bind, init, process, finalize
+- [Metadata API](docs/metadata.md) - Function introspection
+- [Function API Reference](docs/generator-api.md) - Advanced function patterns
+- [Catalog Interface](docs/catalog-interface.md) - DuckDB ATTACH integration
+
+---
+
+## Logging
+
+Workers support `--debug`, `--log-level`, `--log-format`, and `--log-logger` options:
+
+```bash
+# Enable debug logging
+vgi-fixture-worker --debug
+
+# JSON-formatted logs for structured pipelines
+vgi-fixture-worker --log-format json
+
+# Target a specific logger
+vgi-fixture-worker --log-level DEBUG --log-logger vgi.worker
+```
+
+You can also use the `VGI_WORKER_DEBUG=1` environment variable, which enables `--debug` on the worker and stderr passthrough on the client without changing any code or CLI flags:
+
+```bash
+VGI_WORKER_DEBUG=1 python my_script.py
+```
+
+See [CLI Reference](docs/cli.md#worker-logging) for the full list of loggers and options.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/query-farm/vgi-python
+cd vgi-python
+
+uv sync --all-extras        # Install dependencies
+uv run pytest -n auto       # Run tests
+uv run ruff check --fix .   # Lint
+uv run ruff format .        # Format
+uv run mypy vgi/            # Type check
+```
+
+## Requirements
+
+- Python >= 3.12.4
+- pyarrow
+- DuckDB (for SQL integration)
+
+---
+
+## License
+
+Copyright (c) 2025, 2026 Query Farm LLC.
+
+Licensed under the **Query Farm Source-Available License, Version 1.0** — see
+[LICENSE](LICENSE) for the binding terms. In summary (the LICENSE text governs):
+
+- ✅ **Use, copy, modify, and redistribute** the code freely, **including in
+  production and for commercial purposes** — your own internal use, and building
+  products and services on top of VGI.
+- 🚫 Not permitted **without a separate commercial license**: offering a
+  *competing* VGI-equivalent product or service to third parties (hosted,
+  embedded, or as-a-service), or operating a commercial marketplace for such
+  services.
+- ⏳ Each released version converts to the **Apache License, Version 2.0**, ten
+  years after its public release.
+
+For a commercial license or any licensing questions, contact
+[hello@query.farm](mailto:hello@query.farm).