visynx 0.1.0__tar.gz

visynx-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Test & Publish
+
+on:
+  push:
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # 3.9 is the floor declared in pyproject; 3.13 is the ceiling we claim.
+        python-version: ["3.9", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q
+
+  publish:
+    # Only on a version tag, and only if the matrix is green.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing — no API token in secrets
+      contents: read   # a permissions block resets all other scopes to none; checkout needs this
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

visynx-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.ruff_cache/

visynx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VisionForge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

visynx-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: visynx
+Version: 0.1.0
+Summary: Run your VisionForge computer-vision models from Python.
+Project-URL: Homepage, https://visionforge.evo-ss.com
+Project-URL: Documentation, https://visionforge.evo-ss.com/docs/python-quickstart
+Project-URL: Source, https://github.com/manasjohri/Labelling_Package
+Project-URL: Issues, https://github.com/manasjohri/Labelling_Package/issues
+Author: VisionForge
+License: MIT License
+        
+        Copyright (c) 2026 VisionForge
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: computer-vision,detectron2,inference,machine-learning,object-detection,rf-detr,segmentation,visionforge,yolo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pillow>=9.0
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# visynx
+
+Run your [VisionForge](https://visionforge.evo-ss.com) computer-vision models from Python.
+
+Train a model in VisionForge, grab an API key, and you are three lines from predictions —
+detection, segmentation, pose, classification, and semantic segmentation, all through one call.
+
+```bash
+pip install visynx
+```
+
+## Quickstart
+
+```python
+from visynx import Visynx
+
+vf = Visynx(api_key="vf_...")          # or set VISYNX_API_KEY
+model = vf.model("shelf-scanner/3")    # your project name and version
+
+result = model.predict("shelf.jpg", confidence=0.4)
+
+for d in result:
+    print(d.class_name, round(d.confidence, 2), d.box)
+
+result.save("annotated.jpg")
+```
+
+```
+bottle 0.94 [412.0, 118.5, 501.2, 388.0]
+bottle 0.91 [502.6, 121.0, 590.4, 390.7]
+can    0.78 [604.1, 210.3, 664.9, 372.2]
+```
+
+`visynx` pulls in only `requests` and `Pillow`. No OpenCV, no numpy, no torch —
+the models run on VisionForge's GPUs, not yours.
+
+## Find your models
+
+```python
+for m in vf.models():
+    print(m.slug, m.provider, m.display_name)
+# shelf-scanner/3   yolo     Shelf Scanner v3
+# defect-seg/1      rfdetr   Defect Seg v1
+```
+
+`"shelf-scanner/3"` is the model's slug — your project name and its training
+version, the same name you see in the app. A raw `"yolo/<job_id>"` also works
+and skips the lookup.
+
+## What you get back
+
+`predict()` returns a `Result`: iterate it for detections, or reach for the raw
+API payload with `.json()`.
+
+```python
+result = model.predict("shelf.jpg")
+
+len(result)              # 3
+result.detections[0]     # Detection('bottle', 0.94)
+result.json()            # the raw API response, untouched
+
+result.plot()            # a PIL image with boxes drawn on
+result.save("out.jpg")   # ...written to disk
+```
+
+Each `Detection` carries `class_id`, `class_name`, `confidence`, and `box`
+(`[x1, y1, x2, y2]` in absolute pixels). Segmentation models add `polygons`;
+pose models add `keypoints`.
+
+## Anything image-shaped works
+
+```python
+model.predict("shelf.jpg")                  # a path
+model.predict("frames/")                    # a directory -> list of Results
+model.predict(open("shelf.jpg", "rb"))      # an open file
+model.predict(pil_image)                    # a PIL image
+model.predict(numpy_array)                  # a numpy array (from OpenCV, say)
+```
+
+## Beyond boxes
+
+Two flags the hosted GPUs do for you, with nothing extra to install. Each runs a
+second model, so each costs extra credits:
+
+```python
+# Turn every detected box into a precise instance polygon with SAM 2
+result = model.predict("shelf.jpg", segment=True)
+result.detections[0].polygons
+
+# Add a monocular depth map, and a relative distance per detection
+result = model.predict("shelf.jpg", depth=True)
+result.detections[0].depth_median      # 0-1, higher is closer
+result.depth_image.save("depth.png")
+```
+
+Semantic-segmentation models return a dense mask instead of boxes:
+
+```python
+result = model.predict("road.jpg")
+result.semantic["legend"]     # [{'class_id': 1, 'class_name': 'road', ...}]
+result.save("mask.jpg")       # the mask, blended over your image
+```
+
+## Get an API key
+
+In VisionForge, go to **Settings → API Keys**, create a key, and copy the secret —
+it is shown once. Keys start with `vf_`, never expire, and can be locked to
+specific IPs or CIDR ranges. Keep it out of source control:
+
+```python
+vf = Visynx()                      # reads VISYNX_API_KEY
+```
+
+A plain `predict()` call spends 1 Vision Credit; `segment=True` and `depth=True`
+each add a surcharge for the extra model they run. You are charged only after the
+inference succeeds — a failed call is free — and a call retried after a `429` is
+billed once, not twice.
+
+Some endpoints are deliberately not reachable with an API key: batch prediction
+over a whole dataset, live-camera inference, workflow runs, and the AI-labelling
+tools (SAM/DINO/box-prompt). Those run from the VisionForge app with a signed-in
+session. Calling them with a key returns `PermissionDeniedError`.
+
+## Errors
+
+Every failure is a typed exception, and it quotes the response's `X-Request-ID`
+when the server sent one — include it if you contact support. (Authentication
+failures are rejected before that header is assigned, so `401`s carry none.)
+
+| Exception | Means | Do |
+|---|---|---|
+| `AuthenticationError` | key invalid or revoked | create a new key |
+| `PermissionDeniedError` | email unverified, or the key's IP allowlist rejected you | verify your email / check the allowlist |
+| `InsufficientCreditsError` | out of Vision Credits | top up |
+| `ModelNotFoundError` | no such model, or not yours | check `vf.models()` |
+| `PayloadTooLargeError` | image over 50 MB | resize before sending |
+| `RateLimitError` | rate limited, retries exhausted | back off |
+| `MaintenanceError` | platform in maintenance | retry later |
+
+`429`s are retried automatically, honouring the server's `Retry-After`.
+All of these subclass `VisynxError`, so one `except VisynxError` catches everything.
+
+## Self-hosting
+
+Point the client at your own deployment:
+
+```python
+vf = Visynx(api_key="vf_...", api_url="https://visionforge.internal/api")
+```
+
+or set `VISYNX_API_URL`.
+
+## License
+
+MIT

visynx-0.1.0/README.md

@@ -0,0 +1,155 @@
+# visynx
+
+Run your [VisionForge](https://visionforge.evo-ss.com) computer-vision models from Python.
+
+Train a model in VisionForge, grab an API key, and you are three lines from predictions —
+detection, segmentation, pose, classification, and semantic segmentation, all through one call.
+
+```bash
+pip install visynx
+```
+
+## Quickstart
+
+```python
+from visynx import Visynx
+
+vf = Visynx(api_key="vf_...")          # or set VISYNX_API_KEY
+model = vf.model("shelf-scanner/3")    # your project name and version
+
+result = model.predict("shelf.jpg", confidence=0.4)
+
+for d in result:
+    print(d.class_name, round(d.confidence, 2), d.box)
+
+result.save("annotated.jpg")
+```
+
+```
+bottle 0.94 [412.0, 118.5, 501.2, 388.0]
+bottle 0.91 [502.6, 121.0, 590.4, 390.7]
+can    0.78 [604.1, 210.3, 664.9, 372.2]
+```
+
+`visynx` pulls in only `requests` and `Pillow`. No OpenCV, no numpy, no torch —
+the models run on VisionForge's GPUs, not yours.
+
+## Find your models
+
+```python
+for m in vf.models():
+    print(m.slug, m.provider, m.display_name)
+# shelf-scanner/3   yolo     Shelf Scanner v3
+# defect-seg/1      rfdetr   Defect Seg v1
+```
+
+`"shelf-scanner/3"` is the model's slug — your project name and its training
+version, the same name you see in the app. A raw `"yolo/<job_id>"` also works
+and skips the lookup.
+
+## What you get back
+
+`predict()` returns a `Result`: iterate it for detections, or reach for the raw
+API payload with `.json()`.
+
+```python
+result = model.predict("shelf.jpg")
+
+len(result)              # 3
+result.detections[0]     # Detection('bottle', 0.94)
+result.json()            # the raw API response, untouched
+
+result.plot()            # a PIL image with boxes drawn on
+result.save("out.jpg")   # ...written to disk
+```
+
+Each `Detection` carries `class_id`, `class_name`, `confidence`, and `box`
+(`[x1, y1, x2, y2]` in absolute pixels). Segmentation models add `polygons`;
+pose models add `keypoints`.
+
+## Anything image-shaped works
+
+```python
+model.predict("shelf.jpg")                  # a path
+model.predict("frames/")                    # a directory -> list of Results
+model.predict(open("shelf.jpg", "rb"))      # an open file
+model.predict(pil_image)                    # a PIL image
+model.predict(numpy_array)                  # a numpy array (from OpenCV, say)
+```
+
+## Beyond boxes
+
+Two flags the hosted GPUs do for you, with nothing extra to install. Each runs a
+second model, so each costs extra credits:
+
+```python
+# Turn every detected box into a precise instance polygon with SAM 2
+result = model.predict("shelf.jpg", segment=True)
+result.detections[0].polygons
+
+# Add a monocular depth map, and a relative distance per detection
+result = model.predict("shelf.jpg", depth=True)
+result.detections[0].depth_median      # 0-1, higher is closer
+result.depth_image.save("depth.png")
+```
+
+Semantic-segmentation models return a dense mask instead of boxes:
+
+```python
+result = model.predict("road.jpg")
+result.semantic["legend"]     # [{'class_id': 1, 'class_name': 'road', ...}]
+result.save("mask.jpg")       # the mask, blended over your image
+```
+
+## Get an API key
+
+In VisionForge, go to **Settings → API Keys**, create a key, and copy the secret —
+it is shown once. Keys start with `vf_`, never expire, and can be locked to
+specific IPs or CIDR ranges. Keep it out of source control:
+
+```python
+vf = Visynx()                      # reads VISYNX_API_KEY
+```
+
+A plain `predict()` call spends 1 Vision Credit; `segment=True` and `depth=True`
+each add a surcharge for the extra model they run. You are charged only after the
+inference succeeds — a failed call is free — and a call retried after a `429` is
+billed once, not twice.
+
+Some endpoints are deliberately not reachable with an API key: batch prediction
+over a whole dataset, live-camera inference, workflow runs, and the AI-labelling
+tools (SAM/DINO/box-prompt). Those run from the VisionForge app with a signed-in
+session. Calling them with a key returns `PermissionDeniedError`.
+
+## Errors
+
+Every failure is a typed exception, and it quotes the response's `X-Request-ID`
+when the server sent one — include it if you contact support. (Authentication
+failures are rejected before that header is assigned, so `401`s carry none.)
+
+| Exception | Means | Do |
+|---|---|---|
+| `AuthenticationError` | key invalid or revoked | create a new key |
+| `PermissionDeniedError` | email unverified, or the key's IP allowlist rejected you | verify your email / check the allowlist |
+| `InsufficientCreditsError` | out of Vision Credits | top up |
+| `ModelNotFoundError` | no such model, or not yours | check `vf.models()` |
+| `PayloadTooLargeError` | image over 50 MB | resize before sending |
+| `RateLimitError` | rate limited, retries exhausted | back off |
+| `MaintenanceError` | platform in maintenance | retry later |
+
+`429`s are retried automatically, honouring the server's `Retry-After`.
+All of these subclass `VisynxError`, so one `except VisynxError` catches everything.
+
+## Self-hosting
+
+Point the client at your own deployment:
+
+```python
+vf = Visynx(api_key="vf_...", api_url="https://visionforge.internal/api")
+```
+
+or set `VISYNX_API_URL`.
+
+## License
+
+MIT

visynx-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "visynx"
+version = "0.1.0"
+description = "Run your VisionForge computer-vision models from Python."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [{ name = "VisionForge" }]
+keywords = [
+    "computer-vision", "object-detection", "segmentation", "inference",
+    "yolo", "rf-detr", "detectron2", "visionforge", "machine-learning",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.25",
+    "Pillow>=9.0",
+]
+
+[project.urls]
+Homepage = "https://visionforge.evo-ss.com"
+Documentation = "https://visionforge.evo-ss.com/docs/python-quickstart"
+Source = "https://github.com/manasjohri/Labelling_Package"
+Issues = "https://github.com/manasjohri/Labelling_Package/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/visynx"]
+
+[tool.ruff]
+line-length = 110
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

visynx-0.1.0/src/visynx/__init__.py

@@ -0,0 +1,42 @@
+"""visynx — run your VisionForge models from Python.
+
+    from visynx import Visynx
+
+    vf = Visynx(api_key="vf_...")
+    model = vf.model("shelf-scanner/3")
+
+    result = model.predict("shelf.jpg", confidence=0.4)
+    print(result.json())
+    result.save("annotated.jpg")
+"""
+from .client import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    MaintenanceError,
+    ModelNotFoundError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    RateLimitError,
+    Visynx,
+    VisynxError,
+)
+from .model import Model
+from .results import Detection, Result
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthenticationError",
+    "Detection",
+    "InsufficientCreditsError",
+    "MaintenanceError",
+    "Model",
+    "ModelNotFoundError",
+    "PayloadTooLargeError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Result",
+    "Visynx",
+    "VisynxError",
+    "__version__",
+]

visynx-0.1.0/src/visynx/client.py

@@ -0,0 +1,213 @@
+"""HTTP client, auth, and error mapping for the VisionForge API.
+
+One ``requests.Session`` carries the bearer token for every call. The retry and
+error semantics here are not invented — they mirror what the VisionForge API
+already documents (see the platform's "Rate Limits & Error Handling" guide):
+429 is retried honouring ``Retry-After``; 402/401/403 are terminal and mean
+distinct, actionable things; every error quotes the ``X-Request-ID`` header the
+server stamps on every response, because that is what support needs to find the
+matching server log.
+"""
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from typing import Any
+
+import requests
+
+DEFAULT_API_URL = "https://visionforge.evo-ss.com/api"
+
+#: Server-side cap on an inference upload (``MAX_INFERENCE_UPLOAD_BYTES``).
+#: Checked client-side so a doomed 50 MB upload fails instantly instead of
+#: after the transfer.
+MAX_UPLOAD_BYTES = 50 * 1024 * 1024
+
+#: Training backends a model can be served by. Used to tell a raw
+#: ``provider/job_id`` reference from a friendly ``project/version`` slug.
+PROVIDERS = ("yolo", "detectron2", "rfdetr", "smp")
+
+MAX_ATTEMPTS = 4
+
+
+class VisynxError(Exception):
+    """Base class for every error raised by visynx."""
+
+
+class AuthenticationError(VisynxError):
+    """401 — the API key is missing, invalid, or revoked."""
+
+
+class PermissionDeniedError(VisynxError):
+    """403 — email unverified, account deactivated, or the key's IP allowlist rejected you."""
+
+
+class ModelNotFoundError(VisynxError):
+    """404 — no such model, or it isn't yours."""
+
+
+class InsufficientCreditsError(VisynxError):
+    """402 — out of Vision Credits. Not a transient error; top up."""
+
+
+class PayloadTooLargeError(VisynxError):
+    """413 — the image exceeds the inference upload limit."""
+
+
+class RateLimitError(VisynxError):
+    """429 — rate limited, and the retries were exhausted."""
+
+
+class MaintenanceError(VisynxError):
+    """503 — the platform is in maintenance mode."""
+
+
+_STATUS_ERRORS = {
+    401: (AuthenticationError, "API key is invalid or has been revoked"),
+    402: (InsufficientCreditsError, "out of Vision Credits — top up to continue"),
+    403: (
+        PermissionDeniedError,
+        "forbidden — verify your email, or check this key's IP allowlist",
+    ),
+    404: (ModelNotFoundError, "not found"),
+    413: (PayloadTooLargeError, "upload exceeds the size limit"),
+    429: (RateLimitError, "rate limited"),
+    503: (MaintenanceError, "platform is in maintenance mode"),
+}
+
+
+def _normalise(slug: str | None) -> str:
+    """Match slugs forgivingly — a user types whatever separator they saw last."""
+    return (slug or "").strip().strip("/").lower().replace("_", "-")
+
+
+def _retry_after(response) -> float:
+    """Seconds to wait per the server's ``Retry-After``, clamped to something sane."""
+    try:
+        return max(0.0, min(60.0, float(response.headers.get("Retry-After", 5))))
+    except (TypeError, ValueError):
+        return 5.0
+
+
+def _raise_for(response) -> None:
+    """Translate a failed response into the matching typed VisynxError."""
+    try:
+        detail = (response.json() or {}).get("detail")
+    except ValueError:
+        detail = None
+    detail = str(detail) if detail else (response.text or "").strip()[:300]
+
+    error_cls, summary = _STATUS_ERRORS.get(
+        response.status_code, (VisynxError, f"HTTP {response.status_code}")
+    )
+    message = f"{summary}: {detail}" if detail else summary
+    request_id = response.headers.get("X-Request-ID")
+    if request_id:
+        message = f"{message} (request id: {request_id})"
+    raise error_cls(message)
+
+
+class Visynx:
+    """Entry point to the VisionForge inference API.
+
+    >>> vf = Visynx(api_key="vf_...")          # or set VISYNX_API_KEY
+    >>> model = vf.model("shelf-scanner/3")
+    >>> result = model.predict("shelf.jpg", confidence=0.4)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        api_key = api_key or os.environ.get("VISYNX_API_KEY")
+        if not api_key:
+            raise AuthenticationError(
+                "No API key. Pass Visynx(api_key='vf_...') or set the "
+                "VISYNX_API_KEY environment variable. Create a key in "
+                "VisionForge under Settings -> API Keys."
+            )
+        self.api_url = (api_url or os.environ.get("VISYNX_API_URL") or DEFAULT_API_URL).rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers["Authorization"] = f"Bearer {api_key}"
+        self._models_cache: list | None = None
+
+    def __repr__(self) -> str:
+        return f"Visynx(api_url={self.api_url!r})"
+
+    # -- transport ----------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Call the API and return the decoded JSON body, or raise a VisynxError.
+
+        Retries only 429, and only because every caller passes replayable bytes
+        rather than a file handle — a consumed stream could not be re-sent.
+        """
+        url = f"{self.api_url}{path}"
+        # One id for the whole call, reused across retries: the server treats a
+        # repeated (request id, image) pair as the same billable inference, so a
+        # retry can never be charged twice.
+        headers = {"X-Request-ID": uuid.uuid4().hex, **kwargs.pop("headers", {})}
+        for attempt in range(MAX_ATTEMPTS):
+            response = self._session.request(
+                method, url, timeout=self.timeout, headers=headers, **kwargs
+            )
+            if response.status_code == 429 and attempt < MAX_ATTEMPTS - 1:
+                time.sleep(_retry_after(response))
+                continue
+            if not response.ok:
+                _raise_for(response)
+            return response.json()
+        raise RateLimitError(f"rate limited after {MAX_ATTEMPTS} attempts")
+
+    # -- models -------------------------------------------------------------
+
+    def models(self, refresh: bool = False) -> list:
+        """Every trained model on this account that is ready to run.
+
+        Cached on the instance; pass ``refresh=True`` after training something new.
+        """
+        from .model import Model
+
+        if self._models_cache is None or refresh:
+            jobs = self._request("GET", "/train/jobs").get("jobs") or []
+            self._models_cache = [
+                Model._from_job(self, job)
+                for job in jobs
+                if job.get("status") == "completed" and job.get("artifact_available")
+            ]
+        return list(self._models_cache)
+
+    def model(self, ref: str):
+        """Resolve a model by ``"project/version"`` slug or raw ``"provider/job_id"``.
+
+        The slug is what the platform shows you and what you should write in code;
+        the raw form is accepted so scripts holding a job id keep working (and it
+        skips the model-list round trip entirely).
+        """
+        from .model import Model
+
+        if isinstance(ref, Model):
+            return ref
+        ref = str(ref).strip().strip("/")
+        provider, _, tail = ref.partition("/")
+        # "yolo/<uuid>" is a raw reference; "yolo/3" is a slug for a project that
+        # happens to be named "yolo" — a version is always a bare integer.
+        if provider in PROVIDERS and tail and not tail.isdigit():
+            return Model(client=self, provider=provider, job_id=tail)
+
+        wanted = _normalise(ref)
+        matches = [m for m in self.models() if _normalise(m.slug) == wanted]
+        if len(matches) == 1:
+            return matches[0]
+        if not matches:
+            known = ", ".join(sorted(m.slug for m in self.models() if m.slug)) or "none"
+            raise ModelNotFoundError(f"No model {ref!r}. Available: {known}")
+        candidates = ", ".join(f"{m.provider}/{m.job_id}" for m in matches)
+        raise ModelNotFoundError(
+            f"{ref!r} is ambiguous — several projects share that name. "
+            f"Use one of: {candidates}"
+        )

visynx-0.1.0/src/visynx/model.py

@@ -0,0 +1,148 @@
+"""A trained model you can run images through."""
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .client import MAX_UPLOAD_BYTES, PayloadTooLargeError, VisynxError
+from .results import Result
+
+IMAGE_SUFFIXES = {".jpg", ".jpeg", ".png", ".bmp", ".webp", ".tif", ".tiff"}
+
+
+def _encode(image) -> bytes:
+    """PIL image -> JPEG bytes."""
+    buffer = io.BytesIO()
+    image.convert("RGB").save(buffer, format="JPEG", quality=95)
+    return buffer.getvalue()
+
+
+def _to_bytes(source: Any) -> tuple:
+    """Normalise anything image-shaped to ``(filename, bytes)``.
+
+    Accepts a path, raw bytes, an open file, a PIL image, or any object exposing
+    the array interface (a numpy array, without visynx ever importing numpy).
+    """
+    if isinstance(source, (bytes, bytearray)):
+        return "image.jpg", bytes(source)
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        if not path.is_file():
+            raise VisynxError(f"No such image: {path}")
+        return path.name, path.read_bytes()
+    if hasattr(source, "read"):
+        data = source.read()
+        if isinstance(data, str):
+            raise VisynxError("File opened in text mode — open it with 'rb'")
+        return getattr(source, "name", "image.jpg"), data
+    if hasattr(source, "save") and hasattr(source, "mode"):  # PIL.Image
+        return "image.jpg", _encode(source)
+    if hasattr(source, "__array_interface__"):  # numpy array, duck-typed
+        from PIL import Image
+
+        return "image.jpg", _encode(Image.fromarray(source))
+    raise VisynxError(
+        f"Cannot read an image from {type(source).__name__}. Pass a path, bytes, "
+        "a file opened in binary mode, a PIL image, or a numpy array."
+    )
+
+
+@dataclass
+class Model:
+    """A trained model. Get one from :meth:`Visynx.model`, not by constructing it."""
+
+    provider: str
+    job_id: str
+    slug: str | None = None
+    display_name: str | None = None
+    version: int | None = None
+    dataset_id: int | None = None
+    created_at: str | None = None
+    client: Any = field(default=None, repr=False, compare=False)
+    _labels: list | None = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def _from_job(cls, client, job: dict) -> Model:
+        return cls(
+            provider=job.get("provider"),
+            job_id=job.get("job_id"),
+            slug=job.get("slug"),
+            display_name=job.get("display_name"),
+            version=job.get("training_version"),
+            dataset_id=job.get("dataset_id"),
+            created_at=job.get("created_at"),
+            client=client,
+        )
+
+    def __repr__(self) -> str:
+        return f"Model({self.slug or f'{self.provider}/{self.job_id}'!r}, provider={self.provider!r})"
+
+    @property
+    def labels(self) -> list:
+        """Class names the model predicts, in class-id order.
+
+        Read from the weights themselves, so they stay correct even if the source
+        dataset's classes were renamed after training.
+        """
+        if self._labels is None:
+            payload = self.client._request("GET", f"/train/model-labels/{self.job_id}")
+            self._labels = payload.get("labels") or []
+        return self._labels
+
+    def predict(
+        self,
+        source: Any,
+        *,
+        confidence: float = 0.0,
+        segment: bool = False,
+        depth: bool = False,
+    ) -> Result | list:
+        """Run the model on an image.
+
+        Args:
+            source: image path, directory of images, bytes, open binary file,
+                PIL image, or numpy array.
+            confidence: drop detections scoring below this (0-1).
+            segment: refine each detected box into an instance polygon with SAM2.
+            depth: also return a monocular depth map for the image.
+
+        Returns:
+            A :class:`Result`, or a list of them when ``source`` is a directory.
+
+        A plain call spends 1 Vision Credit. ``segment`` and ``depth`` each run a
+        second model on the GPU and cost extra. You are only charged once the
+        inference succeeds, and a retried call is billed once.
+        """
+        if isinstance(source, (str, Path)) and Path(source).is_dir():
+            images = sorted(
+                p for p in Path(source).iterdir() if p.suffix.lower() in IMAGE_SUFFIXES
+            )
+            return [
+                self.predict(p, confidence=confidence, segment=segment, depth=depth)
+                for p in images
+            ]
+
+        filename, data = _to_bytes(source)
+        if not data:
+            raise VisynxError("Image is empty")
+        if len(data) > MAX_UPLOAD_BYTES:
+            raise PayloadTooLargeError(
+                f"{filename} is {len(data) / 1e6:.1f} MB; the inference limit is "
+                f"{MAX_UPLOAD_BYTES // 1024 // 1024} MB. Resize it before sending."
+            )
+
+        params = {}
+        if segment:
+            params["segment"] = "true"
+        if depth:
+            params["depth"] = "true"
+
+        payload = self.client._request(
+            "POST",
+            f"/train/jobs/{self.provider}/{self.job_id}/infer",
+            files={"file": (filename, data)},
+            params=params,
+        )
+        return Result(payload, image_bytes=data, confidence=confidence)

visynx-0.1.0/src/visynx/results.py

@@ -0,0 +1,182 @@
+"""Prediction results, and drawing them on the image.
+
+Field names deliberately mirror the VisionForge API one-for-one — matching the
+wire format is the feature, so anything you learn from ``result.json()`` applies
+to the typed objects and vice versa.
+"""
+from __future__ import annotations
+
+import base64
+import io
+from dataclasses import dataclass, field
+
+#: Deterministic per-class colours, so the same class is the same colour across
+#: every image in a run.
+PALETTE = (
+    "#ef4444", "#3b82f6", "#22c55e", "#f59e0b", "#a855f7", "#06b6d4",
+    "#ec4899", "#84cc16", "#f97316", "#6366f1", "#14b8a6", "#eab308",
+)
+
+
+def _colour(class_id: int | None) -> str:
+    return PALETTE[(class_id or 0) % len(PALETTE)]
+
+
+@dataclass
+class Detection:
+    """One predicted object. ``box`` is ``[x1, y1, x2, y2]`` in absolute pixels.
+
+    Classification models return detections with no ``box``; segmentation models
+    add ``polygons`` (flat ``[x1, y1, x2, y2, ...]`` per instance); pose models
+    add ``keypoints`` (``[[x, y, visibility], ...]``).
+    """
+
+    class_id: int | None = None
+    class_name: str | None = None
+    confidence: float = 0.0
+    box: list | None = None
+    polygons: list = field(default_factory=list)
+    keypoints: list = field(default_factory=list)
+    #: Relative depth (0-1, higher is closer). Only set when ``depth=True``.
+    depth_median: float | None = None
+
+    @classmethod
+    def _from_json(cls, data: dict) -> Detection:
+        return cls(
+            class_id=data.get("class_id"),
+            class_name=data.get("class_name"),
+            confidence=float(data.get("confidence") or 0.0),
+            box=data.get("box"),
+            polygons=data.get("polygons") or [],
+            keypoints=data.get("keypoints") or [],
+            depth_median=data.get("depth_median"),
+        )
+
+    def __repr__(self) -> str:
+        return f"Detection({self.class_name!r}, {self.confidence:.2f})"
+
+
+def _decode_png(b64: str):
+    from PIL import Image
+
+    return Image.open(io.BytesIO(base64.b64decode(b64)))
+
+
+class Result:
+    """What one image came back as.
+
+    Iterate it for detections, call :meth:`json` for the raw payload, or
+    :meth:`plot` / :meth:`save` to see it.
+    """
+
+    def __init__(self, payload: dict, image_bytes: bytes | None = None, confidence: float = 0.0):
+        self._payload = payload
+        self._image_bytes = image_bytes
+        self.job_id = payload.get("job_id")
+        self.detections = [
+            Detection._from_json(d)
+            for d in (payload.get("detections") or [])
+            if float(d.get("confidence") or 0.0) >= confidence
+        ]
+        #: Dense per-pixel overlay from a semantic-segmentation (smp) model.
+        #: ``{width, height, overlay_png_b64, legend}``; ``detections`` is empty.
+        self.semantic: dict | None = payload.get("semantic")
+        #: Monocular depth map, when ``depth=True`` was passed.
+        self.depth: dict | None = payload.get("depth")
+
+    def __len__(self) -> int:
+        return len(self.detections)
+
+    def __iter__(self):
+        return iter(self.detections)
+
+    def __repr__(self) -> str:
+        if self.semantic:
+            classes = len(self.semantic.get("legend") or [])
+            return f"Result(semantic, {classes} classes)"
+        return f"Result({len(self.detections)} detections)"
+
+    def json(self) -> dict:
+        """The raw API response, unmodified."""
+        return self._payload
+
+    @property
+    def image(self):
+        """The image that was sent, as a PIL image."""
+        if not self._image_bytes:
+            raise ValueError("This result carries no source image")
+        from PIL import Image
+
+        return Image.open(io.BytesIO(self._image_bytes))
+
+    @property
+    def depth_image(self):
+        """The depth map as a colourised PIL image, or None if depth wasn't requested."""
+        if not self.depth or not self.depth.get("overlay_png_b64"):
+            return None
+        return _decode_png(self.depth["overlay_png_b64"]).convert("RGB")
+
+    def plot(self):
+        """Draw the predictions onto the source image and return a PIL image."""
+        from PIL import Image, ImageDraw
+
+        canvas = self.image.convert("RGBA")
+
+        # Semantic models return a transparent RGBA mask to blend, not boxes.
+        if self.semantic and self.semantic.get("overlay_png_b64"):
+            overlay = _decode_png(self.semantic["overlay_png_b64"]).convert("RGBA")
+            if overlay.size != canvas.size:
+                overlay = overlay.resize(canvas.size, Image.NEAREST)
+            canvas = Image.alpha_composite(canvas, overlay)
+
+        draw = ImageDraw.Draw(canvas)
+        width = max(2, canvas.width // 400)
+        font = _font(canvas.width)
+
+        # Classification models have no geometry — stack the scores in a corner.
+        boxless = [d for d in self.detections if not d.box and not d.polygons]
+        for index, det in enumerate(boxless):
+            _label(draw, (width * 2, width * 2 + index * (width * 9)),
+                   f"{det.class_name} {det.confidence:.2f}", _colour(det.class_id), font)
+
+        for det in self.detections:
+            colour = _colour(det.class_id)
+            for polygon in det.polygons:
+                if len(polygon) >= 6:
+                    points = list(zip(polygon[0::2], polygon[1::2]))
+                    draw.line(points + points[:1], fill=colour, width=width)
+            if det.box and len(det.box) == 4:
+                x1, y1, x2, y2 = (float(v) for v in det.box)
+                draw.rectangle((x1, y1, x2, y2), outline=colour, width=width)
+                _label(draw, (x1, y1), f"{det.class_name} {det.confidence:.2f}", colour, font)
+            for point in det.keypoints:
+                if len(point) >= 2:
+                    x, y = float(point[0]), float(point[1])
+                    draw.ellipse((x - width * 2, y - width * 2, x + width * 2, y + width * 2), fill=colour)
+
+        return canvas.convert("RGB")
+
+    def save(self, path) -> str:
+        """Write :meth:`plot`'s annotated image to ``path``. Returns the path."""
+        self.plot().save(path)
+        return str(path)
+
+
+def _font(image_width: int):
+    from PIL import ImageFont
+
+    size = max(12, image_width // 60)
+    try:  # Pillow >= 10.1 can scale the built-in font
+        return ImageFont.load_default(size=size)
+    except TypeError:
+        return ImageFont.load_default()
+
+
+def _label(draw, anchor, text: str, colour: str, font) -> None:
+    """A filled chip with the class name, kept inside the image."""
+    x, y = anchor
+    left, top, right, bottom = draw.textbbox((0, 0), text, font=font)
+    w, h = right - left, bottom - top
+    y = max(0, y - h - 4)
+    draw.rectangle((x, y, x + w + 6, y + h + 6), fill=colour)
+    draw.text((x + 3, y + 2), text, fill="white", font=font)

visynx-0.1.0/tests/test_visynx.py

@@ -0,0 +1,266 @@
+"""No network. A fake session stands in for the API and returns canned payloads."""
+import io
+import json
+
+import pytest
+from PIL import Image
+
+from visynx import (
+    InsufficientCreditsError,
+    ModelNotFoundError,
+    PayloadTooLargeError,
+    Visynx,
+    VisynxError,
+)
+
+
+class FakeResponse:
+    def __init__(self, status_code=200, payload=None, headers=None):
+        self.status_code = status_code
+        self.ok = status_code < 400
+        self.headers = headers or {}
+        self._payload = payload if payload is not None else {}
+        self.text = json.dumps(self._payload)
+
+    def json(self):
+        return self._payload
+
+
+class FakeSession:
+    """Replays a queue of responses and records what was asked for."""
+
+    def __init__(self, *responses):
+        self.headers = {}
+        self.queue = list(responses)
+        self.calls = []
+
+    def request(self, method, url, **kwargs):
+        self.calls.append((method, url, kwargs))
+        return self.queue.pop(0) if len(self.queue) > 1 else self.queue[0]
+
+
+def client(*responses):
+    vf = Visynx(api_key="vf_test", api_url="https://example.test/api")
+    vf._session = FakeSession(*responses)
+    return vf
+
+
+def job(slug, job_id, provider="yolo", **extra):
+    return {
+        "slug": slug, "job_id": job_id, "provider": provider,
+        "status": "completed", "artifact_available": True, **extra,
+    }
+
+
+def image_bytes(size=(64, 48), colour="navy"):
+    buffer = io.BytesIO()
+    Image.new("RGB", size, colour).save(buffer, format="JPEG")
+    return buffer.getvalue()
+
+
+DETECTIONS = {
+    "success": True,
+    "job_id": "abc",
+    "detections": [
+        {"class_id": 0, "class_name": "bottle", "confidence": 0.91, "box": [5, 5, 30, 40]},
+        {"class_id": 1, "class_name": "can", "confidence": 0.12, "box": [35, 5, 60, 40]},
+    ],
+}
+
+
+# -- auth ---------------------------------------------------------------------
+
+def test_missing_key_fails_loudly(monkeypatch):
+    monkeypatch.delenv("VISYNX_API_KEY", raising=False)
+    with pytest.raises(Exception, match="VISYNX_API_KEY"):
+        Visynx()
+
+
+def test_key_from_environment(monkeypatch):
+    monkeypatch.setenv("VISYNX_API_KEY", "vf_from_env")
+    assert Visynx()._session.headers["Authorization"] == "Bearer vf_from_env"
+
+
+# -- model resolution ---------------------------------------------------------
+
+def test_slug_resolves_to_provider_and_job_id():
+    vf = client(FakeResponse(payload={"jobs": [job("hungary/1", "j1"), job("shelf-scanner/3", "j2")]}))
+    model = vf.model("shelf-scanner/3")
+    assert (model.provider, model.job_id) == ("yolo", "j2")
+
+
+@pytest.mark.parametrize("typed", ["shelf_scanner/3", "Shelf-Scanner/3", " shelf-scanner/3 "])
+def test_slug_matching_forgives_separator_and_case(typed):
+    vf = client(FakeResponse(payload={"jobs": [job("shelf-scanner/3", "j2")]}))
+    assert vf.model(typed).job_id == "j2"
+
+
+def test_raw_reference_skips_the_lookup():
+    vf = client()  # empty queue: any HTTP call would raise IndexError
+    model = vf.model("rfdetr/8f2a-uuid")
+    assert (model.provider, model.job_id) == ("rfdetr", "8f2a-uuid")
+
+
+def test_ambiguous_slug_names_the_candidates():
+    vf = client(FakeResponse(payload={"jobs": [job("shelf/3", "j1"), job("shelf/3", "j2", "rfdetr")]}))
+    with pytest.raises(ModelNotFoundError, match="ambiguous"):
+        vf.model("shelf/3")
+
+
+def test_unknown_slug_lists_what_exists():
+    vf = client(FakeResponse(payload={"jobs": [job("hungary/1", "j1")]}))
+    with pytest.raises(ModelNotFoundError, match="hungary/1"):
+        vf.model("nope/9")
+
+
+def test_only_runnable_models_are_listed():
+    vf = client(FakeResponse(payload={"jobs": [
+        job("done/1", "j1"),
+        job("running/2", "j2", status="training"),
+        job("noweights/3", "j3", artifact_available=False),
+    ]}))
+    assert [m.slug for m in vf.models()] == ["done/1"]
+
+
+# -- errors -------------------------------------------------------------------
+
+def test_429_is_retried_with_the_servers_backoff(monkeypatch):
+    slept = []
+    monkeypatch.setattr("visynx.client.time.sleep", slept.append)
+    vf = client(
+        FakeResponse(429, headers={"Retry-After": "7"}),
+        FakeResponse(payload={"jobs": []}),
+    )
+    assert vf.models() == []
+    assert slept == [7.0]
+
+
+def test_one_request_id_is_reused_across_retries(monkeypatch):
+    """The server bills a (request id, image) pair once, so the retry of a 429
+    must carry the SAME id — otherwise a retry could be charged twice."""
+    monkeypatch.setattr("visynx.client.time.sleep", lambda _: None)
+    vf = client(FakeResponse(429, headers={"Retry-After": "1"}), FakeResponse(payload={"jobs": []}))
+    vf.models()
+    ids = [kwargs["headers"]["X-Request-ID"] for _, _, kwargs in vf._session.calls]
+    assert len(ids) == 2 and ids[0] == ids[1]
+
+
+def test_separate_calls_get_separate_request_ids():
+    vf = client(FakeResponse(payload=DETECTIONS))
+    model = vf.model("yolo/abc")
+    model.predict(image_bytes())
+    model.predict(image_bytes())
+    ids = {kwargs["headers"]["X-Request-ID"] for _, _, kwargs in vf._session.calls}
+    assert len(ids) == 2, "distinct calls must not dedupe into one charge"
+
+
+def test_402_is_terminal_and_quotes_the_request_id():
+    vf = client(FakeResponse(402, {"detail": "Not enough credits"}, {"X-Request-ID": "req-99"}))
+    with pytest.raises(InsufficientCreditsError, match="req-99"):
+        vf.models()
+
+
+def test_403_explains_both_causes():
+    vf = client(FakeResponse(403, {"detail": "IP not allowed"}))
+    with pytest.raises(VisynxError, match="IP allowlist"):
+        vf.models()
+
+
+# -- predict ------------------------------------------------------------------
+
+def test_confidence_filters_low_scores():
+    vf = client(FakeResponse(payload=DETECTIONS))
+    result = vf.model("yolo/abc").predict(image_bytes(), confidence=0.5)
+    assert [d.class_name for d in result] == ["bottle"]
+    assert len(result.json()["detections"]) == 2, "raw payload stays untouched"
+
+
+def test_segment_and_depth_reach_the_server():
+    vf = client(FakeResponse(payload=DETECTIONS))
+    vf.model("yolo/abc").predict(image_bytes(), segment=True, depth=True)
+    _, url, kwargs = vf._session.calls[0]
+    assert url.endswith("/train/jobs/yolo/abc/infer")
+    assert kwargs["params"] == {"segment": "true", "depth": "true"}
+
+
+def test_oversized_image_never_reaches_the_network():
+    vf = client()
+    with pytest.raises(PayloadTooLargeError, match="MB"):
+        vf.model("yolo/abc").predict(b"x" * (51 * 1024 * 1024))
+
+
+def test_unreadable_source_is_rejected():
+    vf = client()
+    with pytest.raises(VisynxError, match="Cannot read an image"):
+        vf.model("yolo/abc").predict(42)
+
+
+def test_directory_returns_one_result_per_image(tmp_path):
+    for name in ("a.jpg", "b.png", "notes.txt"):
+        (tmp_path / name).write_bytes(image_bytes() if name != "notes.txt" else b"ignore me")
+    vf = client(FakeResponse(payload=DETECTIONS))
+    results = vf.model("yolo/abc").predict(tmp_path)
+    assert len(results) == 2, "the .txt must be skipped"
+
+
+def test_pil_image_is_encoded_and_sent():
+    vf = client(FakeResponse(payload=DETECTIONS))
+    vf.model("yolo/abc").predict(Image.new("RGB", (32, 32), "red"))
+    assert vf._session.calls[0][2]["files"]["file"][1][:2] == b"\xff\xd8", "sent JPEG bytes"
+
+
+# -- results ------------------------------------------------------------------
+
+def test_semantic_models_expose_a_mask_not_detections():
+    overlay = io.BytesIO()
+    Image.new("RGBA", (64, 48), (255, 0, 0, 140)).save(overlay, format="PNG")
+    import base64
+
+    payload = {"success": True, "job_id": "s1", "semantic": {
+        "width": 64, "height": 48,
+        "overlay_png_b64": base64.b64encode(overlay.getvalue()).decode(),
+        "legend": [{"class_id": 1, "class_name": "road", "color": "rgb(255,0,0)"}],
+    }}
+    vf = client(FakeResponse(payload=payload))
+    result = vf.model("smp/s1").predict(image_bytes())
+    assert result.detections == []
+    assert result.semantic["legend"][0]["class_name"] == "road"
+    assert result.plot().size == (64, 48), "the mask composites over the source"
+
+
+def test_plot_draws_and_save_writes_a_real_image(tmp_path):
+    vf = client(FakeResponse(payload=DETECTIONS))
+    result = vf.model("yolo/abc").predict(image_bytes(colour="black"))
+    out = tmp_path / "out.jpg"
+    result.save(out)
+    written = Image.open(out)
+    assert written.size == (64, 48)
+    assert len(set(written.convert("RGB").tobytes())) > 1, "something was drawn on the black image"
+
+
+def test_polygons_and_keypoints_plot_without_error():
+    payload = {"job_id": "p", "detections": [{
+        "class_id": 0, "class_name": "person", "confidence": 0.8, "box": [2, 2, 60, 44],
+        "polygons": [[4, 4, 50, 4, 50, 40, 4, 40]],
+        "keypoints": [[10, 10, 1], [20, 20, 1]],
+    }]}
+    vf = client(FakeResponse(payload=payload))
+    assert vf.model("yolo/abc").predict(image_bytes()).plot().size == (64, 48)
+
+
+def test_classification_results_have_no_box():
+    payload = {"job_id": "c", "detections": [
+        {"class_id": 3, "class_name": "ripe", "confidence": 0.77},
+    ]}
+    vf = client(FakeResponse(payload=payload))
+    result = vf.model("yolo/abc").predict(image_bytes())
+    assert result.detections[0].box is None
+    assert result.plot().size == (64, 48)
+
+
+def test_labels_are_fetched_lazily_and_cached():
+    vf = client(FakeResponse(payload={"labels": ["bottle", "can"]}))
+    model = vf.model("yolo/abc")
+    assert model.labels == ["bottle", "can"]
+    assert model.labels == ["bottle", "can"]
+    assert len(vf._session.calls) == 1, "second access must not re-request"