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

vgi/_test_fixtures/table/_common.py

@@ -61,7 +61,7 @@ class CountBatchArgs:
     """
 
     count: Annotated[int, Arg(0, doc="Number of rows to generate", ge=0)]
-    batch_size: Annotated[int, Arg("batch_size", default=1000, doc="Batch size for output", ge=1)]
+    batch_size: Annotated[int, Arg("batch_size", default=2048, doc="Batch size for output", ge=1)]
 
 
 @dataclass(slots=True, frozen=True)
@@ -91,7 +91,7 @@ class _BaseSequenceFunction(TableFunctionGenerator[Any, CountdownState]):
     NUMPY_DTYPE: ClassVar[type[np.generic]] = np.int64
     STATS_ARROW_TYPE: ClassVar[pa.DataType] = pa.int64()
     STATS_COLUMN_NAME: ClassVar[str] = "n"
-    BATCH_SIZE_FALLBACK: ClassVar[int] = 1000
+    BATCH_SIZE_FALLBACK: ClassVar[int] = 2048
 
     @classmethod
     def initial_state(cls, params: ProcessParams[Any]) -> CountdownState:

vgi/_test_fixtures/worker.py

@@ -320,6 +320,7 @@ _EXAMPLE_CATALOG = Catalog(
     default_schema="main",
     comment="Example VGI catalog for testing",
     tags={"source": "vgi-fixture-worker", "version": "1"},
+    source_url="https://github.com/query-farm/vgi-python",
     schemas=[
         Schema(
             name="main",

vgi/argument_spec.py

@@ -38,6 +38,7 @@ __all__ = [
     "VGI_VARARGS_TRUE",
     "VGI_CONST_KEY",
     "VGI_CONST_TRUE",
+    "VGI_DOC_KEY",
 ]
 
 # =============================================================================
@@ -61,6 +62,11 @@ VGI_VARARGS_TRUE = b"true"
 VGI_CONST_KEY = b"vgi_const"
 VGI_CONST_TRUE = b"true"
 
+# Key carrying the per-argument description (UTF-8 text). Presence-only: the key
+# is omitted entirely when there is no doc (absent = undocumented). The
+# ``vgi_doc_*`` prefix is reserved for future per-argument doc variants.
+VGI_DOC_KEY = b"vgi_doc"
+
 
 def _argument_spec_sort_key(spec: "ArgumentSpec") -> tuple[int, int | str]:
     """Sort key: positional first (by index), then named (alphabetically)."""
@@ -98,6 +104,9 @@ class ArgumentSpec:
         is_const: True if this argument is constant-folded ([`ConstParam`][]).
             Constant arguments are scalar values known at planning time,
             rather than columnar data processed at runtime.
+        doc: Optional human/agent-facing description of the argument. Surfaced
+            through the catalog as the ``vgi_doc`` Arrow field metadata key
+            (UTF-8); empty string means undocumented.
 
     Note:
         For named arguments, the Python attribute name (``name``) and the SQL
@@ -119,6 +128,7 @@ class ArgumentSpec:
     is_any_type: bool = False
     is_varargs: bool = False
     is_const: bool = False
+    doc: str = ""
 
     def __repr__(self) -> str:
         """Return concise repr showing key attributes."""
@@ -197,6 +207,10 @@ def argument_specs_to_schema(specs: Sequence[ArgumentSpec]) -> pa.Schema:
         if spec.is_const:
             metadata[VGI_CONST_KEY] = VGI_CONST_TRUE
 
+        # Per-argument description (UTF-8; presence-only — omit when empty)
+        if spec.doc:
+            metadata[VGI_DOC_KEY] = spec.doc.encode("utf-8")
+
         # Create field with or without metadata
         field = pa.field(
             spec.name,
@@ -246,6 +260,10 @@ def schema_to_argument_specs(schema: pa.Schema) -> list[ArgumentSpec]:
         # Check const
         is_const = metadata.get(VGI_CONST_KEY) == VGI_CONST_TRUE
 
+        # Per-argument description (UTF-8; absent = undocumented)
+        doc_bytes = metadata.get(VGI_DOC_KEY)
+        doc = doc_bytes.decode("utf-8") if doc_bytes else ""
+
         specs.append(
             ArgumentSpec(
                 name=field.name,
@@ -255,6 +273,7 @@ def schema_to_argument_specs(schema: pa.Schema) -> list[ArgumentSpec]:
                 is_any_type=is_any_type,
                 is_varargs=is_varargs,
                 is_const=is_const,
+                doc=doc,
             )
         )
 
@@ -312,6 +331,7 @@ def extract_argument_specs(
                 is_any_type=param_arg.is_any,
                 is_varargs=param_arg.varargs,
                 is_const=False,
+                doc=param_arg.doc or "",
             )
         )
 
@@ -328,6 +348,7 @@ def extract_argument_specs(
                 is_any_type=const_arg.is_any,
                 is_varargs=const_arg.varargs,
                 is_const=True,
+                doc=const_arg.doc or "",
             )
         )
 
@@ -392,6 +413,7 @@ def extract_argument_specs(
                     is_any_type=is_any_type,
                     is_varargs=arg_instance.varargs,
                     is_const=getattr(arg_instance, "const", False),
+                    doc=getattr(arg_instance, "doc", "") or "",
                 )
             )
 
@@ -466,6 +488,7 @@ def extract_argument_specs(
                         is_any_type=is_any_type,
                         is_varargs=is_varargs,
                         is_const=is_const,
+                        doc=getattr(arg_legacy, "doc", "") or "",
                     )
                 )
 

vgi/catalog/catalog_interface.py

@@ -2319,6 +2319,7 @@ class ReadOnlyCatalogInterface(CatalogInterface):
                 implementation_version=None,
                 data_version_spec=None,
                 attach_option_specs=[spec.serialize() for spec in self.attach_option_specs],
+                source_url=self.catalog.source_url if self.catalog is not None else None,
             )
         ]
 

vgi/catalog/descriptors.py

@@ -873,6 +873,10 @@ class Catalog:
         schemas: Sequence of Schema objects defining the catalog contents.
         comment: Optional comment describing the catalog.
         tags: Optional key-value tags associated with the catalog.
+        source_url: Where this worker's code lives — repo, build, or docs
+            homepage. ``None`` (the default) when the worker doesn't advertise
+            a source location. Surfaced via the ``catalog_catalogs()`` discovery
+            record (``CatalogInfo.source_url``).
 
     """
 
@@ -881,6 +885,7 @@ class Catalog:
     schemas: Sequence[Schema] = ()
     comment: str | None = None
     tags: dict[str, str] = field(default_factory=dict)
+    source_url: str | None = None
 
     def __post_init__(self) -> None:
         """Validate catalog configuration."""

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.8.3
+Version: 0.8.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

{vgi_python-0.8.3.dist-info → vgi_python-0.8.5.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=fVO17BDDfjnTMUrRoILNr2oFLTl4KKedMObFUk2GRrI,17072
+vgi/argument_spec.py,sha256=FFtCNVXhUnEvft51HICOVA7jGJilDW0CHYeyuYexGsg,18142
 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
@@ -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=JPTVPONIoWL9VXN8mINoJH6_Puy1Byj5VOg_fsbw8ws,71171
+vgi/_test_fixtures/worker.py,sha256=5G3shpiPoKWV_DP28UN1LYNp1wIJ2Q-TB8mJ3qok2q4,71230
 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
@@ -71,7 +71,7 @@ vgi/_test_fixtures/scalar/type_info.py,sha256=2WeTxakT-_tcWybPfkCrAHVAMOadFN3tb8
 vgi/_test_fixtures/schema_reconcile/__init__.py,sha256=rCCtM5bd67-PTPeIYg9SCJaKUSglA6YeXsedQBEUlmA,1324
 vgi/_test_fixtures/schema_reconcile/worker.py,sha256=qkGRdKvI2AKItenlribd3cvUfvWUwPbAc2WrW7_7Ijc,23570
 vgi/_test_fixtures/table/__init__.py,sha256=PndeOVcsqi17XLwn0VnmPabjw3tFUfvOQFtETMOCjaU,7371
-vgi/_test_fixtures/table/_common.py,sha256=tO18gShWidcKcdHYn1FIEXDWzC2SwGsVMnA84r9Y3qs,5961
+vgi/_test_fixtures/table/_common.py,sha256=9HYDW8aH7eD7V3CabTWTE7ZeVL_ELxUXdiJfuyuZjaQ,5961
 vgi/_test_fixtures/table/batch_index.py,sha256=P5ds0xgikuEQanSEWVWKMLbdvIzUeJraI-GuSoPdb6U,11641
 vgi/_test_fixtures/table/batch_index_broken.py,sha256=kZOGrLL7ZW1rmwPmNEYRmiF_vqIfHsfXioq5vKPWHk0,7314
 vgi/_test_fixtures/table/catalog_scans.py,sha256=5j1Sx02-HWK7bFurDu4e9HiS3Q9BmBukA3sAErH4GHE,5080
@@ -98,8 +98,8 @@ 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=Ni3kkxXLQAtsQaDnRQMXih6r6Dcm6uACiHrQSE64SlY,120141
-vgi/catalog/descriptors.py,sha256=5LAP6xrWCebEG1EkD0lLNBYX-LBCcxylj_-q3SXxRA8,39047
+vgi/catalog/catalog_interface.py,sha256=aCMSpYczcEb11TmOFdaGTN_F_yOywyR2go1Z6vC_0zY,120231
+vgi/catalog/descriptors.py,sha256=oH-Ld02yQ5oUJb7J9sqGYwhZwaWzZiL3ZPtublmKXzc,39366
 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
@@ -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.3.dist-info/METADATA,sha256=1IObmLQGq14cxyOL9Q-3rdWmX5HR9y9br2CJf7az7R0,24725
-vgi_python-0.8.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-vgi_python-0.8.3.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.8.3.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.8.3.dist-info/RECORD,,
+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,,