visynx 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+visynx/__init__.py,sha256=OekP2u7XLrzwVBCjODZrrttZGvgCRoEYos8_uN3MlwA,893
+visynx/client.py,sha256=5wgcltVaSu57k0uR-HsFH4uYwC330Q0Gsk1_16LB95Y,8122
+visynx/model.py,sha256=cWDXZU-X5jH8WBMQYJ1MpAVM4BFu-G27EnbKxWJsgck,5335
+visynx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+visynx/results.py,sha256=pi3Ukv-p5NWaFIucCUnY0rtsbdraNpxRXLELs3N-4Mc,6803
+visynx-0.1.0.dist-info/METADATA,sha256=GkE8C37wxJ6zoZpWPCPEYJmlatDLBnJjKoxjY4yEIII,7823
+visynx-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+visynx-0.1.0.dist-info/licenses/LICENSE,sha256=Vs6853kI20vijlKlB1Jo17u6X_mNPjwdc3xPtvB2zxI,1068
+visynx-0.1.0.dist-info/RECORD,,

visynx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

visynx-0.1.0.dist-info/licenses/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.