labeltify 0.2.0__py3-none-any.whl

labeltify/__init__.py

@@ -0,0 +1,12 @@
+"""LabelTify client for DeepStream, OpenCV, and any pipeline that uploads frames."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import DEFAULT_BASE_URL, LabelTifyClient, LabelTifyError
+
+try:
+    __version__ = version("labeltify")
+except PackageNotFoundError:  # running from a checkout
+    __version__ = "0.0.0"
+
+__all__ = ["DEFAULT_BASE_URL", "LabelTifyClient", "LabelTifyError", "__version__"]

labeltify/client.py

@@ -0,0 +1,188 @@
+"""Upload frames and optional annotations into LabelTify.
+
+Auth is a pipeline token from the dataset Upload page. The token already knows its org.
+
+    from labeltify import LabelTifyClient
+    client = LabelTifyClient("labeltify_…")
+    image = client.upload_image(dataset_id, jpeg_bytes, filename="cam01.jpg", camera="cam-01", pipeline="ds-prod", trigger="low_confidence")
+    client.upload_file(dataset_id, "frames/cam01.jpg")
+    client.propose(dataset_id, image["id"], boxes, model_ref="deepstream@1")
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import random
+import time
+import urllib.error
+import urllib.request
+import uuid
+from pathlib import Path
+from typing import Any
+
+DEFAULT_BASE_URL = "https://api.labeltify.com"
+RETRY_STATUS = {408, 425, 429, 500, 502, 503, 504}
+
+
+class LabelTifyError(RuntimeError):
+    """The API answered with an error, or kept failing after retries."""
+
+    def __init__(self, message: str, status: int | None = None, body: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class LabelTifyClient:
+    """Pipeline-token client. Only the token is required.
+
+    ``token`` falls back to the ``LABELTIFY_TOKEN`` environment variable. ``org`` is looked up from the
+    token on first use. Transient failures (timeouts, 429, 5xx) are retried with exponential backoff.
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        org: str | None = None,
+        *,
+        timeout: float = 60.0,
+        max_retries: int = 4,
+        backoff: float = 0.5,
+    ) -> None:
+        # Older callers passed (base_url, token, org) positionally.
+        if token and token.startswith(("http://", "https://")) and base_url and not base_url.startswith(("http://", "https://")):
+            token, base_url = base_url, token
+        token = token or os.environ.get("LABELTIFY_TOKEN")
+        if not token:
+            raise ValueError("Pass a pipeline token or set LABELTIFY_TOKEN.")
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self._org = org
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff = backoff
+
+    @property
+    def org(self) -> str:
+        """The org slug the token belongs to."""
+        if self._org is None:
+            me = self._request("GET", "/api/me")
+            orgs = me.get("orgs") if isinstance(me, dict) else None
+            if not orgs:
+                raise LabelTifyError("This token is not linked to an org.")
+            self._org = orgs[0]["slug"]
+        return self._org
+
+    def _request(self, method: str, path: str, body: bytes | None = None, content_type: str | None = None) -> Any:
+        headers = {"authorization": f"Bearer {self.token}", "user-agent": "labeltify-python"}
+        if content_type:
+            headers["content-type"] = content_type
+        attempt = 0
+        while True:
+            req = urllib.request.Request(f"{self.base_url}{path}", data=body, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                    raw = res.read()
+                    return json.loads(raw.decode("utf-8")) if raw else None
+            except urllib.error.HTTPError as e:
+                text = e.read().decode("utf-8", "replace")
+                if e.code in RETRY_STATUS and attempt < self.max_retries:
+                    self._sleep(attempt, e.headers.get("retry-after"))
+                    attempt += 1
+                    continue
+                raise LabelTifyError(f"LabelTify API {e.code}: {_message(text)}", e.code, text) from e
+            except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+                if attempt < self.max_retries:
+                    self._sleep(attempt, None)
+                    attempt += 1
+                    continue
+                raise LabelTifyError(f"Could not reach {self.base_url}: {e}") from e
+
+    def _sleep(self, attempt: int, retry_after: str | None) -> None:
+        try:
+            wait = float(retry_after) if retry_after else self.backoff * (2**attempt)
+        except ValueError:
+            wait = self.backoff * (2**attempt)
+        time.sleep(min(wait, 30.0) + random.uniform(0, self.backoff / 2))
+
+    def upload_image(
+        self,
+        dataset_id: str,
+        data: bytes,
+        filename: str,
+        *,
+        camera: str | None = None,
+        pipeline: str | None = None,
+        trigger: str | None = None,
+        content_type: str = "image/jpeg",
+        labels: bytes | None = None,
+        labels_filename: str = "labels.json",
+        work_state: str | None = None,
+    ) -> dict[str, Any]:
+        """Upload one image. ``labels`` is optional COCO, LabelTify, or YOLO JSON for it."""
+        boundary = f"----labeltify{uuid.uuid4().hex}"
+        parts: list[bytes] = []
+
+        def field(name: str, value: str) -> None:
+            parts.append(f"--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"\r\n\r\n{value}\r\n".encode())
+
+        def file(name: str, fname: str, ctype: str, payload: bytes) -> None:
+            head = (
+                f"--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"; filename=\"{fname}\"\r\n"
+                f"Content-Type: {ctype}\r\n\r\n"
+            ).encode()
+            parts.append(head + payload + b"\r\n")
+
+        if camera:
+            field("camera", camera)
+        if pipeline:
+            field("pipeline", pipeline)
+        if trigger:
+            field("trigger", trigger)
+        if work_state:
+            field("workState", work_state)
+        file("file", filename, content_type, data)
+        if labels is not None:
+            file("file", labels_filename, "application/json", labels)
+        parts.append(f"--{boundary}--\r\n".encode())
+        result = self._request(
+            "POST",
+            f"/api/orgs/{self.org}/datasets/{dataset_id}/images",
+            b"".join(parts),
+            f"multipart/form-data; boundary={boundary}",
+        )
+        items = result.get("items") if isinstance(result, dict) else None
+        if not items:
+            raise LabelTifyError("upload returned no items")
+        return items[0]
+
+    def upload_file(self, dataset_id: str, path: str | os.PathLike[str], **kwargs: Any) -> dict[str, Any]:
+        """Upload an image file from disk. Keyword arguments are passed to ``upload_image``."""
+        p = Path(path)
+        kwargs.setdefault("content_type", mimetypes.guess_type(p.name)[0] or "image/jpeg")
+        return self.upload_image(dataset_id, p.read_bytes(), p.name, **kwargs)
+
+    def propose(
+        self,
+        dataset_id: str,
+        image_id: str,
+        proposals: list[dict[str, Any]],
+        *,
+        model_ref: str,
+        uncertainty: float = 0.5,
+    ) -> dict[str, Any]:
+        """Send model proposals for an image to the Loop review queue."""
+        payload = json.dumps(
+            {"imageId": image_id, "modelRef": model_ref, "proposals": proposals, "uncertainty": uncertainty}
+        ).encode()
+        return self._request("POST", f"/api/orgs/{self.org}/datasets/{dataset_id}/al/tasks", payload, "application/json")
+
+
+def _message(text: str) -> str:
+    try:
+        return json.loads(text)["error"]["message"]
+    except (ValueError, KeyError, TypeError):
+        return text[:500]

labeltify-0.2.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: labeltify
+Version: 0.2.0
+Summary: Upload frames and optional annotations into LabelTify with a pipeline token.
+Author: CleverTify
+Project-URL: Homepage, https://labeltify.com
+Project-URL: Source, https://github.com/CleverTify/LabelTify/tree/main/clients/python
+Keywords: labeltify,annotation,computer-vision,deepstream,active-learning,dataset
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# labeltify
+
+Upload frames, and optionally their annotations, into [LabelTify](https://labeltify.com) from DeepStream, OpenCV, Ultralytics, or any Python pipeline. The only thing it needs is a pipeline token.
+
+```sh
+pip install labeltify
+```
+
+1. On the dataset **Upload** page, create a pipeline token.
+2. Upload:
+
+```python
+from labeltify import LabelTifyClient
+
+client = LabelTifyClient("labeltify_…")  # or set LABELTIFY_TOKEN and call LabelTifyClient()
+
+img = client.upload_image(
+    "DATASET_ID",
+    jpeg_bytes,
+    filename="cam01.jpg",
+    camera="cam-01",
+    pipeline="ds-prod",
+    trigger="low_confidence",
+)
+client.upload_file("DATASET_ID", "frames/cam02.jpg", camera="cam-02")
+```
+
+The token knows its org, so you don't pass one. Timeouts, `429`, and `5xx` responses are retried with exponential backoff (`max_retries=4` by default). Anything else raises `LabelTifyError` with the API's message and `.status`.
+
+Annotations are optional. Pass `labels` (COCO, LabelTify, or YOLO JSON bytes) and `work_state` (`done`, `in_progress`, `unsure`, or `untouched`). Images with no labels stay untouched. If labels are sent and `work_state` is omitted, those images are marked Done.
+
+Send model proposals to the Loop review queue:
+
+```python
+client.propose(
+    "DATASET_ID",
+    img["id"],
+    [{"type": "bbox", "id": "p1", "classId": "car", "box": {"x": 0.1, "y": 0.1, "w": 0.2, "h": 0.2}, "source": "model", "confidence": 0.4}],
+    model_ref="deepstream@1",
+    uncertainty=0.8,
+)
+```
+
+Boxes are normalized `[0,1]`. Camera, pipeline, and trigger are stored on the image so Loop can filter by them.
+
+Local API: `LabelTifyClient("labeltify_…", base_url="http://localhost:8787")`.
+
+## Develop
+
+```sh
+pip install -e "clients/python[test]"
+pytest clients/python/tests
+```
+
+Bump `version` in `pyproject.toml` to publish. Each new version that lands on `main` is published to PyPI by `.github/workflows/publish-python.yml`.

labeltify-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+labeltify/__init__.py,sha256=XWJvFZbFgUpjYppyUrqwgp4GiHQkJ1nlxcVsOcAncoM,429
+labeltify/client.py,sha256=TmCPlXZo4kO8FZH4QQQhG1NZuJYSFVs3Q9koPJAgV9U,7443
+labeltify-0.2.0.dist-info/METADATA,sha256=ciMJBG4Qnck7tEnlgZ6WYSOfjB75btNlxIbC0QANUYk,2732
+labeltify-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+labeltify-0.2.0.dist-info/top_level.txt,sha256=s8avvtBzwNWUyPjJ_Dvpfi2SES8a0ACVGOwsftLk_es,10
+labeltify-0.2.0.dist-info/RECORD,,

labeltify-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

labeltify-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+labeltify