labeltify 0.2.0__tar.gz

labeltify-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,55 @@
+# 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/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-0.2.0/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/labeltify.egg-info/PKG-INFO

@@ -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/labeltify.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+labeltify/__init__.py
+labeltify/client.py
+labeltify.egg-info/PKG-INFO
+labeltify.egg-info/SOURCES.txt
+labeltify.egg-info/dependency_links.txt
+labeltify.egg-info/requires.txt
+labeltify.egg-info/top_level.txt
+tests/test_client.py

labeltify-0.2.0/labeltify.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

labeltify-0.2.0/labeltify.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=8

labeltify-0.2.0/labeltify.egg-info/top_level.txt

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

labeltify-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "labeltify"
+# Bump this to publish. .github/workflows/publish-python.yml releases each new version pushed to main.
+version = "0.2.0"
+description = "Upload frames and optional annotations into LabelTify with a pipeline token."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "CleverTify" }]
+keywords = ["labeltify", "annotation", "computer-vision", "deepstream", "active-learning", "dataset"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://labeltify.com"
+Source = "https://github.com/CleverTify/LabelTify/tree/main/clients/python"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["labeltify*"]

labeltify-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

labeltify-0.2.0/tests/test_client.py

@@ -0,0 +1,127 @@
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import pytest
+
+from labeltify import LabelTifyClient, LabelTifyError
+
+
+class Api:
+    """A tiny stand-in for the LabelTify API that records requests and can fail on demand."""
+
+    def __init__(self):
+        self.requests = []
+        self.fail_next = []  # status codes to return before succeeding
+
+    def handle(self, handler: BaseHTTPRequestHandler):
+        length = int(handler.headers.get("content-length") or 0)
+        body = handler.rfile.read(length) if length else b""
+        self.requests.append((handler.command, handler.path, handler.headers, body))
+        if handler.headers.get("authorization") != "Bearer labeltify_test":
+            return self.reply(handler, 401, {"error": {"message": "bad token"}})
+        if self.fail_next:
+            return self.reply(handler, self.fail_next.pop(0), {"error": {"message": "busy"}})
+        if handler.path == "/api/me":
+            return self.reply(handler, 200, {"orgs": [{"slug": "acme"}]})
+        if handler.path.endswith("/images"):
+            return self.reply(handler, 201, {"items": [{"id": "img-1"}]})
+        if handler.path.endswith("/al/tasks"):
+            return self.reply(handler, 201, {"id": "task-1", "echo": json.loads(body)})
+        return self.reply(handler, 404, {"error": {"message": "not found"}})
+
+    @staticmethod
+    def reply(handler, status, payload):
+        raw = json.dumps(payload).encode()
+        handler.send_response(status)
+        handler.send_header("content-type", "application/json")
+        handler.send_header("content-length", str(len(raw)))
+        if status == 429:
+            handler.send_header("retry-after", "0")
+        handler.end_headers()
+        handler.wfile.write(raw)
+
+
+@pytest.fixture
+def api():
+    state = Api()
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            state.handle(self)
+
+        def do_POST(self):
+            state.handle(self)
+
+        def log_message(self, *args):
+            pass
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    state.url = f"http://127.0.0.1:{server.server_address[1]}"
+    yield state
+    server.shutdown()
+
+
+def test_token_is_all_it_needs(api):
+    client = LabelTifyClient("labeltify_test", base_url=api.url, backoff=0)
+    image = client.upload_image("ds-1", b"\xff\xd8jpeg", "cam01.jpg", camera="cam-01", pipeline="ds", trigger="motion")
+    assert image == {"id": "img-1"}
+    assert client.org == "acme"
+    method, path, headers, body = api.requests[-1]
+    assert (method, path) == ("POST", "/api/orgs/acme/datasets/ds-1/images")
+    assert headers["content-type"].startswith("multipart/form-data; boundary=")
+    for part in (b'name="camera"\r\n\r\ncam-01', b'name="pipeline"\r\n\r\nds', b'name="trigger"\r\n\r\nmotion', b'filename="cam01.jpg"'):
+        assert part in body
+
+
+def test_token_from_environment(api, monkeypatch):
+    monkeypatch.setenv("LABELTIFY_TOKEN", "labeltify_test")
+    client = LabelTifyClient(base_url=api.url)
+    assert client.org == "acme"
+
+
+def test_missing_token_is_a_clear_error(monkeypatch):
+    monkeypatch.delenv("LABELTIFY_TOKEN", raising=False)
+    with pytest.raises(ValueError, match="LABELTIFY_TOKEN"):
+        LabelTifyClient()
+
+
+def test_old_positional_order_still_works(api):
+    client = LabelTifyClient(api.url, "labeltify_test", "acme")
+    assert client.base_url == api.url
+    assert client.upload_image("ds-1", b"x", "a.jpg")["id"] == "img-1"
+
+
+def test_retries_busy_responses(api):
+    api.fail_next = [503, 429]
+    client = LabelTifyClient("labeltify_test", base_url=api.url, org="acme", backoff=0)
+    assert client.upload_image("ds-1", b"x", "a.jpg")["id"] == "img-1"
+    assert len(api.requests) == 3
+
+
+def test_gives_up_with_the_api_message(api):
+    client = LabelTifyClient("labeltify_wrong", base_url=api.url, org="acme", backoff=0)
+    with pytest.raises(LabelTifyError, match="401: bad token") as err:
+        client.upload_image("ds-1", b"x", "a.jpg")
+    assert err.value.status == 401
+    assert len(api.requests) == 1
+
+
+def test_labels_and_upload_file(api, tmp_path):
+    frame = tmp_path / "frame.png"
+    frame.write_bytes(b"\x89PNG")
+    client = LabelTifyClient("labeltify_test", base_url=api.url, org="acme", backoff=0)
+    client.upload_file("ds-1", frame, labels=b'{"images": []}', work_state="done")
+    body = api.requests[-1][3]
+    assert b"Content-Type: image/png" in body
+    assert b'filename="labels.json"' in body
+    assert b'name="workState"\r\n\r\ndone' in body
+
+
+def test_propose(api):
+    client = LabelTifyClient("labeltify_test", base_url=api.url, org="acme")
+    task = client.propose("ds-1", "img-1", [{"classId": "car"}], model_ref="deepstream@1")
+    assert task["echo"]["modelRef"] == "deepstream@1"
+    assert api.requests[-1][1] == "/api/orgs/acme/datasets/ds-1/al/tasks"