Bring vision worker to vgi-lint-clean; wire metadata-quality CI gate

Bump vgi-python floor to >=0.8.4 (declarative Catalog gains source_url) and
refresh uv.lock. Add catalog/schema/table-function metadata so
`vgi-lint --fail-on info` reports 0 findings (100/100):

- Catalog: comment, source_url, and tags (vgi.description_llm/_md, author,
  copyright, license=MIT, support_contact, support_policy_url).
- Schema main: vgi.description_llm / vgi.description_md tags.
- Each dynamic-schema table function (classify x4, image_classes): a
  vgi.columns_md Markdown table of its returned columns.

Add a separate `metadata-quality` CI job that builds the worker and runs
Query-farm/vgi-lint-check@v1 with fail-on: info.

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

Author: rustyconover

.github/workflows/ci.yml

@@ -139,3 +139,27 @@ jobs:
         run: ci/run-integration.sh
         env:
           TRANSPORT: ${{ matrix.transport }}
+
+  # Catalog/function metadata quality gate. Builds the worker (same as the
+  # integration job) and runs the signed vgi-lint metadata linter, failing on
+  # any finding at info severity or above.
+  metadata-quality:
+    name: Metadata quality (vgi-lint)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+
+      - name: Install the worker (from the lockfile, with the http extra)
+        run: uv sync --frozen --python 3.13 --extra http
+
+      - name: vgi-lint
+        uses: Query-farm/vgi-lint-check@v1
+        with:
+          location: "uv run --python 3.13 vision_worker.py"
+          fail-on: info

pyproject.toml

@@ -30,7 +30,7 @@ classifiers = [
 ]
 requires-python = ">=3.13"
 dependencies = [
-    "vgi-python>=0.8.3",
+    "vgi-python>=0.8.4",
     "onnxruntime>=1.17",
     "pillow>=10",
     "numpy>=1.26",
@@ -43,7 +43,7 @@ dependencies = [
 # in addition to stdio. That path needs vgi-python's `http` extra (waitress).
 # CI's http transport leg installs this via `uv sync --extra http`.
 http = [
-    "vgi-python[http]>=0.8.3",
+    "vgi-python[http]>=0.8.4",
 ]
 dev = [
     "pytest>=8",

uv.lock

@@ -131,6 +131,23 @@ def _emit_cursor(state: ScanState, out: OutputCollector, schema: pa.Schema) -> N
     ]
 )
 
+# Markdown column docs for the dynamic table-function schemas. DuckDB can't expose a
+# table function's returned columns statically, so each function advertises them via a
+# `vgi.columns_md` tag (consumed by describe/listing tooling and the metadata linter).
+_CLASSIFY_COLUMNS_MD = (
+    "| column | type | description |\n"
+    "|---|---|---|\n"
+    "| `label` | VARCHAR | Predicted ImageNet class label. |\n"
+    "| `confidence` | DOUBLE | Softmax probability in [0, 1]; rows are confidence descending. |"
+)
+
+_CLASSES_COLUMNS_MD = (
+    "| column | type | description |\n"
+    "|---|---|---|\n"
+    "| `idx` | INTEGER | 0-based class index into the model's output. |\n"
+    "| `label` | VARCHAR | ImageNet class label. |"
+)
+
 
 def _classify_batch(preds: list[tuple[str, float]] | None, schema: pa.Schema) -> pa.RecordBatch:
     """Build the full ``(label, confidence)`` batch for a set of predictions.
@@ -188,6 +205,7 @@ class Meta:
         name = "classify"
         description = "Top-5 ImageNet predictions (label, confidence) for an image BLOB"
         categories = ["vision", "classification"]
+        tags = {"vgi.columns_md": _CLASSIFY_COLUMNS_MD}
         examples = [
             FunctionExample(
                 sql="SELECT * FROM vision.classify((SELECT image FROM photos LIMIT 1))",
@@ -226,6 +244,7 @@ class Meta:
         name = "classify"
         description = "Top-k ImageNet predictions (label, confidence) for an image BLOB"
         categories = ["vision", "classification"]
+        tags = {"vgi.columns_md": _CLASSIFY_COLUMNS_MD}
         examples = [
             FunctionExample(
                 sql="SELECT * FROM vision.classify((SELECT image FROM photos LIMIT 1), 10)",
@@ -281,6 +300,7 @@ class Meta:
         name = "classify"
         description = "Top-5 ImageNet predictions for an image file path"
         categories = ["vision", "classification"]
+        tags = {"vgi.columns_md": _CLASSIFY_COLUMNS_MD}
         examples = [
             FunctionExample(
                 sql="SELECT * FROM vision.classify('/tmp/cat.jpg')",
@@ -319,6 +339,7 @@ class Meta:
         name = "classify"
         description = "Top-k ImageNet predictions for an image file path"
         categories = ["vision", "classification"]
+        tags = {"vgi.columns_md": _CLASSIFY_COLUMNS_MD}
         examples = [
             FunctionExample(
                 sql="SELECT * FROM vision.classify('/tmp/cat.jpg', 10)",
@@ -368,6 +389,7 @@ class Meta:
         name = "image_classes"
         description = "The model's ImageNet label set: (idx, label), 1000 rows"
         categories = ["vision", "classification"]
+        tags = {"vgi.columns_md": _CLASSES_COLUMNS_MD}
         examples = [
             FunctionExample(
                 sql="SELECT count(*) FROM vision.image_classes()",

vgi_vision/tables.py

@@ -1,7 +1,7 @@
 # /// script
 # requires-python = ">=3.13"
 # dependencies = [
-#     "vgi-python[http]>=0.8.3",
+#     "vgi-python[http]>=0.8.4",
 #     "onnxruntime>=1.17",
 #     "pillow>=10",
 #     "numpy>=1.26",
@@ -42,13 +42,63 @@
 from vgi_vision.scalars import SCALAR_FUNCTIONS
 from vgi_vision.tables import TABLE_FUNCTIONS
 
+_CATALOG_DESCRIPTION_LLM = (
+    "Run image classification on image blobs (or image file paths) directly in SQL. "
+    "Given the raw bytes of a PNG/JPEG/etc. image, returns ImageNet-1k labels: the single "
+    "most likely label (`top_label`), the top-k (label, confidence) predictions "
+    "(`classify`), or the model's full 1000-class label set (`image_classes`). The "
+    "classifier is a permissively-licensed MobileNetV2 ONNX model. Use it to tag, filter, "
+    "or group images by what they depict — e.g. find photos of cats, label a column of "
+    "image blobs, or rank an image's most probable subjects."
+)
+
+_CATALOG_DESCRIPTION_MD = (
+    "# vision\n\n"
+    "Image classification (ImageNet-1k) on image blobs as DuckDB SQL functions, via VGI. "
+    "Inference runs out-of-process on a permissively-licensed MobileNetV2 ONNX model "
+    "(Apache-2.0 weights) through onnxruntime.\n\n"
+    "- **`top_label(image)` / `top_label(path)`** — scalar: the #1 predicted label per row.\n"
+    "- **`classify(image[, top_k])` / `classify(path[, top_k])`** — table: top-k "
+    "`(label, confidence)` predictions, confidence descending.\n"
+    "- **`image_classes()`** — table: the model's full `(idx, label)` label set (1000 rows).\n\n"
+    "Untrusted/malformed images yield SQL NULL (or no rows), never a crash."
+)
+
+_SCHEMA_DESCRIPTION_LLM = (
+    "Image-classification functions over image blobs and file paths: predict the top "
+    "ImageNet label (`top_label`), the top-k (label, confidence) predictions (`classify`), "
+    "and enumerate the model's class set (`image_classes`)."
+)
+
+_SCHEMA_DESCRIPTION_MD = (
+    "Image-classification functions: `top_label` (scalar), `classify` (table), and "
+    "`image_classes` (table) over a MobileNetV2 ImageNet-1k ONNX model."
+)
+
+_CATALOG_TAGS = {
+    "vgi.description_llm": _CATALOG_DESCRIPTION_LLM,
+    "vgi.description_md": _CATALOG_DESCRIPTION_MD,
+    "vgi.author": "Query.Farm",
+    "vgi.copyright": "Copyright 2026 Query Farm LLC - https://query.farm",
+    "vgi.license": "MIT",
+    "vgi.support_contact": "https://github.com/Query-farm/vgi-vision/issues",
+    "vgi.support_policy_url": "https://github.com/Query-farm/vgi-vision/blob/main/README.md",
+}
+
 _VISION_CATALOG = Catalog(
     name="vision",
     default_schema="main",
+    comment="Image classification (ImageNet) on image blobs and file paths for SQL.",
+    source_url="https://github.com/Query-farm/vgi-vision",
+    tags=_CATALOG_TAGS,
     schemas=[
         Schema(
             name="main",
             comment="Image classification (ImageNet) on image blobs for SQL",
+            tags={
+                "vgi.description_llm": _SCHEMA_DESCRIPTION_LLM,
+                "vgi.description_md": _SCHEMA_DESCRIPTION_MD,
+            },
             functions=[*SCALAR_FUNCTIONS, *TABLE_FUNCTIONS],
         ),
     ],