quiclabel-coco-sync 0.0.1

CLI to incrementally sync a QuicLabel COCO dataset (annotations + images) from quiclabel-admin

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:

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:

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:

uv tool install quiclabel-coco-sync
quiclabel-coco-sync path/to/annotations.json --admin-url ... --api-key ...

From the monorepo (contributors)

# 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:

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

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:

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/.