quiclabel-coco-sync 0.0.1__tar.gz

quiclabel_coco_sync-0.0.1/.gitignore

@@ -0,0 +1,79 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+dist/
+build/
+.vite/
+.next/
+.turbo/
+out/
+
+# Environment
+.env
+.env.local
+.env.*.local
+.env.deploy
+.env.production
+deploy/.env.production
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*.tsbuildinfo
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Testing
+coverage/
+test-results/
+playwright-report/
+
+# E2E runtime files
+.e2e-pids
+.e2e-jobs
+.e2e-*.log
+
+# Prisma
+packages/database/prisma/migrations/**/migration_lock.toml
+
+# MedSight infer-app-client
+*.onnx
+apps/infer-app-client/assets/trt_cache/
+apps/infer-app-client/dist/
+apps/infer-app-client/installer_output/
+apps/infer-app-client/outputs/
+.pytest_cache/
+
+# Temporary
+*.tmp
+*.bak
+apps/infer_app/
+
+ssim_stats.json
+ssim_all/
+ssim_debug/.teamwork/
+
+.teamwork/
+
+# Teamwork agent scratch
+.teamwork-ids.json
+

quiclabel_coco_sync-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 weavejam / quiclabel contributors
+
+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.

quiclabel_coco_sync-0.0.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: quiclabel-coco-sync
+Version: 0.0.1
+Summary: CLI to incrementally sync a QuicLabel COCO dataset (annotations + images) from quiclabel-admin
+Project-URL: Homepage, https://github.com/weavejam/quiclabel/tree/main/apps/quiclabel-sync-project-coco
+Project-URL: Repository, https://github.com/weavejam/quiclabel
+Project-URL: Issues, https://github.com/weavejam/quiclabel/issues
+Author: weavejam / quiclabel contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: annotation,coco,computer-vision,dataset,quiclabel,sync
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Image Recognition
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# quiclabel-coco-sync
+
+CLI to incrementally sync a QuicLabel COCO dataset (annotations + images)
+from `quiclabel-admin`. Pulls a fresh `annotations-YYYYMMDD-HHMMSS.json`
+next to your existing dataset and multi-threadedly downloads only the
+images you don't already have.
+
+## Prerequisites
+
+- **uv** — Python package & runtime manager. Install:
+  - macOS / Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+  - Windows: `winget install astral-sh.uv` (or `irm https://astral.sh/uv/install.ps1 | iex`)
+  - via pipx: `pipx install uv`
+- **An API key** — get one from quiclabel-admin: *Settings → API Keys → New key*.
+  Copy the `qk_...` value immediately (it's only shown once).
+
+## Quick start (from PyPI — recommended)
+
+No clone, no install — `uvx` downloads, caches and runs in one shot:
+
+```bash
+uvx quiclabel-coco-sync path/to/annotations.json \
+  --admin-url https://quiclabel-admin.example.com \
+  --api-key qk_xxxxxxxxxxxxxxxxxxxxxx
+```
+
+Or set env vars and call it bare:
+
+```bash
+export QUICLABEL_ADMIN_URL=https://quiclabel-admin.example.com
+export QUICLABEL_API_KEY=qk_xxxxxxxxxxxxxxxxxxxxxx
+uvx quiclabel-coco-sync path/to/annotations.json
+```
+
+Prefer a persistent install? Use `uv tool`:
+
+```bash
+uv tool install quiclabel-coco-sync
+quiclabel-coco-sync path/to/annotations.json --admin-url ... --api-key ...
+```
+
+## From the monorepo (contributors)
+
+```bash
+# From the repo root
+pnpm sync-project-coco path/to/annotations.json \
+  --admin-url https://quiclabel-admin.example.com \
+  --api-key qk_xxxxxxxxxxxxxxxxxxxxxx
+```
+
+Or directly with `uv` against this app directory:
+
+```bash
+cd apps/quiclabel-sync-project-coco
+uv sync
+uv run quiclabel-coco-sync path/to/annotations.json \
+  --admin-url https://quiclabel-admin.example.com \
+  --api-key qk_xxxxxxxxxxxxxxxxxxxxxx
+```
+
+## What it does
+
+1. Reads `path/to/annotations.json` and its `meta` block (added by the COCO exporter).
+2. Calls `GET /api/v1/projects/<project_id>/coco` with the same filters,
+   paging by cursor — so 10k+ task projects don't blow up server memory.
+3. Writes `path/to/annotations-20260519-143045.json` (timestamped — never
+   overwrites your input).
+4. Diffs `task_id` sets, downloads any missing images to `path/to/images/`
+   using a thread pool. Files already on disk are skipped by file name.
+
+The old `annotations.json` and the existing `images/*` files are never touched.
+
+## Configuration priority
+
+Each value is resolved in this order — first wins:
+
+1. CLI flag (`--project-id`, `--statuses`, …)
+2. Env var (`QUICLABEL_ADMIN_URL`, `QUICLABEL_API_KEY`)
+3. `meta` block of the input json
+
+If anything required is missing from all three, the CLI exits with a clear
+message naming the missing key and where to provide it.
+
+## Recovery
+
+- **Partial failure** (some images failed mid-run): just re-run the same
+  command. Already-downloaded files are skipped by file name, so retry only
+  fetches the remaining ones. The CLI tells you this in the failure summary.
+- **Corrupt image file**: delete it, then re-run.
+- **A `.part` file in `images/`** indicates a crashed download. Safe to delete.
+
+## Development
+
+```bash
+cd apps/quiclabel-sync-project-coco
+uv sync --group dev
+uv run pytest
+```
+
+## Releasing to PyPI (maintainers)
+
+Manual release flow until CI is wired up:
+
+```bash
+cd apps/quiclabel-sync-project-coco
+
+# 1. bump version in pyproject.toml
+# 2. build sdist + wheel
+uv build
+
+# 3. publish (uses UV_PUBLISH_TOKEN or prompts)
+uv publish
+```
+
+Get a PyPI API token at <https://pypi.org/manage/account/token/>.
+

quiclabel_coco_sync-0.0.1/README.md

@@ -0,0 +1,116 @@
+# quiclabel-coco-sync
+
+CLI to incrementally sync a QuicLabel COCO dataset (annotations + images)
+from `quiclabel-admin`. Pulls a fresh `annotations-YYYYMMDD-HHMMSS.json`
+next to your existing dataset and multi-threadedly downloads only the
+images you don't already have.
+
+## Prerequisites
+
+- **uv** — Python package & runtime manager. Install:
+  - macOS / Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+  - Windows: `winget install astral-sh.uv` (or `irm https://astral.sh/uv/install.ps1 | iex`)
+  - via pipx: `pipx install uv`
+- **An API key** — get one from quiclabel-admin: *Settings → API Keys → New key*.
+  Copy the `qk_...` value immediately (it's only shown once).
+
+## Quick start (from PyPI — recommended)
+
+No clone, no install — `uvx` downloads, caches and runs in one shot:
+
+```bash
+uvx quiclabel-coco-sync path/to/annotations.json \
+  --admin-url https://quiclabel-admin.example.com \
+  --api-key qk_xxxxxxxxxxxxxxxxxxxxxx
+```
+
+Or set env vars and call it bare:
+
+```bash
+export QUICLABEL_ADMIN_URL=https://quiclabel-admin.example.com
+export QUICLABEL_API_KEY=qk_xxxxxxxxxxxxxxxxxxxxxx
+uvx quiclabel-coco-sync path/to/annotations.json
+```
+
+Prefer a persistent install? Use `uv tool`:
+
+```bash
+uv tool install quiclabel-coco-sync
+quiclabel-coco-sync path/to/annotations.json --admin-url ... --api-key ...
+```
+
+## From the monorepo (contributors)
+
+```bash
+# From the repo root
+pnpm sync-project-coco path/to/annotations.json \
+  --admin-url https://quiclabel-admin.example.com \
+  --api-key qk_xxxxxxxxxxxxxxxxxxxxxx
+```
+
+Or directly with `uv` against this app directory:
+
+```bash
+cd apps/quiclabel-sync-project-coco
+uv sync
+uv run quiclabel-coco-sync path/to/annotations.json \
+  --admin-url https://quiclabel-admin.example.com \
+  --api-key qk_xxxxxxxxxxxxxxxxxxxxxx
+```
+
+## What it does
+
+1. Reads `path/to/annotations.json` and its `meta` block (added by the COCO exporter).
+2. Calls `GET /api/v1/projects/<project_id>/coco` with the same filters,
+   paging by cursor — so 10k+ task projects don't blow up server memory.
+3. Writes `path/to/annotations-20260519-143045.json` (timestamped — never
+   overwrites your input).
+4. Diffs `task_id` sets, downloads any missing images to `path/to/images/`
+   using a thread pool. Files already on disk are skipped by file name.
+
+The old `annotations.json` and the existing `images/*` files are never touched.
+
+## Configuration priority
+
+Each value is resolved in this order — first wins:
+
+1. CLI flag (`--project-id`, `--statuses`, …)
+2. Env var (`QUICLABEL_ADMIN_URL`, `QUICLABEL_API_KEY`)
+3. `meta` block of the input json
+
+If anything required is missing from all three, the CLI exits with a clear
+message naming the missing key and where to provide it.
+
+## Recovery
+
+- **Partial failure** (some images failed mid-run): just re-run the same
+  command. Already-downloaded files are skipped by file name, so retry only
+  fetches the remaining ones. The CLI tells you this in the failure summary.
+- **Corrupt image file**: delete it, then re-run.
+- **A `.part` file in `images/`** indicates a crashed download. Safe to delete.
+
+## Development
+
+```bash
+cd apps/quiclabel-sync-project-coco
+uv sync --group dev
+uv run pytest
+```
+
+## Releasing to PyPI (maintainers)
+
+Manual release flow until CI is wired up:
+
+```bash
+cd apps/quiclabel-sync-project-coco
+
+# 1. bump version in pyproject.toml
+# 2. build sdist + wheel
+uv build
+
+# 3. publish (uses UV_PUBLISH_TOKEN or prompts)
+uv publish
+```
+
+Get a PyPI API token at <https://pypi.org/manage/account/token/>.
+

quiclabel_coco_sync-0.0.1/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "quiclabel-coco-sync"
+version = "0.0.1"
+description = "CLI to incrementally sync a QuicLabel COCO dataset (annotations + images) from quiclabel-admin"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    { name = "weavejam / quiclabel contributors" },
+]
+keywords = ["quiclabel", "coco", "annotation", "dataset", "sync", "computer-vision"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "click>=8.1",
+    "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://github.com/weavejam/quiclabel/tree/main/apps/quiclabel-sync-project-coco"
+Repository = "https://github.com/weavejam/quiclabel"
+Issues = "https://github.com/weavejam/quiclabel/issues"
+
+[project.scripts]
+quiclabel-coco-sync = "quiclabel_sync_project_coco.cli:main"
+sync-project-coco = "quiclabel_sync_project_coco.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quiclabel_sync_project_coco"]

quiclabel_coco_sync-0.0.1/src/quiclabel_sync_project_coco/__init__.py

@@ -0,0 +1,3 @@
+"""Incremental sync for QuicLabel COCO datasets."""
+
+__version__ = "0.1.0"

quiclabel_coco_sync-0.0.1/src/quiclabel_sync_project_coco/api.py

@@ -0,0 +1,97 @@
+"""HTTP client for GET /api/v1/projects/:id/coco with cursor pagination."""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Iterator
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class ApiError(Exception):
+    """Raised for non-retryable HTTP failures (4xx other than 429)."""
+
+
+def _request_page(
+    session: requests.Session,
+    url: str,
+    params: dict[str, Any],
+    headers: dict[str, str],
+    *,
+    max_retries: int = 3,
+    timeout: float = 30.0,
+) -> dict[str, Any]:
+    """Fetch one page with retry-on-5xx. Raises ApiError for 4xx."""
+    for attempt in range(max_retries + 1):
+        try:
+            resp = session.get(url, params=params, headers=headers, timeout=timeout)
+        except requests.RequestException as e:
+            if attempt == max_retries:
+                raise ApiError(f"Network error after {max_retries + 1} attempts: {e}") from e
+            logger.warning("network error (attempt %d): %s", attempt + 1, e)
+            time.sleep(2**attempt)
+            continue
+
+        if resp.status_code == 200:
+            return resp.json()
+
+        if resp.status_code in (401, 403):
+            raise ApiError(
+                f"Authentication failed ({resp.status_code}): check --api-key"
+            )
+
+        if resp.status_code in RETRYABLE_STATUS and attempt < max_retries:
+            logger.warning(
+                "server %d (attempt %d), retrying", resp.status_code, attempt + 1
+            )
+            time.sleep(2**attempt)
+            continue
+
+        raise ApiError(f"API error {resp.status_code}: {resp.text[:500]}")
+
+    raise ApiError("retry loop exhausted")  # pragma: no cover
+
+
+def iter_pages(
+    admin_url: str,
+    api_key: str,
+    project_id: str,
+    *,
+    statuses: list[str],
+    tag_ids: list[str],
+    image_source: str,
+    limit: int = 500,
+    session: requests.Session | None = None,
+) -> Iterator[dict[str, Any]]:
+    """Yield each page dict in turn. The first page has meta/info/categories;
+    subsequent pages only have images/annotations/next_cursor."""
+    s = session or requests.Session()
+    headers = {"Authorization": f"Bearer {api_key}"}
+    url = f"{admin_url}/api/v1/projects/{project_id}/coco"
+    params: dict[str, Any] = {
+        "statuses": ",".join(statuses),
+        "image_source": image_source,
+        "limit": limit,
+    }
+    if tag_ids:
+        params["tag_ids"] = ",".join(tag_ids)
+
+    cursor: str | None = None
+    page_num = 0
+    while True:
+        page_params = dict(params)
+        if cursor:
+            page_params["cursor"] = cursor
+
+        page = _request_page(s, url, page_params, headers)
+        page_num += 1
+        logger.info("page %d: %d images", page_num, len(page.get("images") or []))
+        yield page
+
+        cursor = page.get("next_cursor")
+        if not cursor:
+            return