Add ask_vlm method for cloud VLM alert verification

[srnangi]

What

Adds Groundlight.ask_vlm(media, query, model_id) for VLM-based alert verification. Calls POST /v1/vlm-verifications on the Groundlight cloud (AWS Bedrock) and returns a VLMVerificationResult with verdict (YES/NO/UNSURE), confidence, reasoning, and token cost fields.

Pairs with the janzu PR (zuuul#6519). No local inference — VLM runs entirely in the cloud.

How

• media accepts 1–8 images (single image or list). Accepts numpy BGR arrays, PIL Images, bytes, BytesIO/BufferedReader, or filename strings — encoded via the existing parse_supported_image_types utility.
• POSTs multipart/form-data: media parts as image/jpeg files; query and model_id as form fields (not URL params, so the prompt never leaks into access logs).
• model_id is a friendly alias (e.g. "gpt-5.4", "claude-sonnet-4.5") — the server maps it to the real Bedrock model ID. Defaults to the server-configured default.
• Exports VLMVerificationResult from the package root.

Usage

gl = Groundlight()

# Single image
result = gl.ask_vlm(frame, query="Is there a fire in this image?")
if result.verdict == "YES":
    emit_alert()

# Full frame + cropped ROI — describe each in the query
result = gl.ask_vlm(
    media=[full_frame, roi_crop],
    query="Image 1 is the full camera frame; image 2 is the cropped region "
          "a detector flagged. Is there really a fire?",
)
print(result.confidence, result.reasoning, result.total_cost_usd)

Changes

• src/groundlight/client.py: ask_vlm method + VLMVerificationResult dataclass
• src/groundlight/__init__.py: exports VLMVerificationResult
• test/unit/test_ask_vlm.py: 8 unit tests with mocked HTTP

Bug fix included

sanitize_endpoint_url strips the trailing slash from self.endpoint, so the original code produced .../device-apiv1/vlm-verifications. Fixed to /v1/vlm-verifications (with leading slash). Regression test added.

Testing

8 unit tests (mocked HTTP, no live server):

• Single numpy image encoded as JPEG multipart
• Dual-image sends two media parts
• query/model_id sent as form fields, not URL params
• No model_id omits the field entirely
• More than 8 media items raises ValueError
• URL has correct path (/device-api/v1/vlm-verifications)
• Bytes image accepted
• Result fields parsed correctly

🤖 Generated with Claude Code