finwave-wavefront 0.1.0__py3-none-any.whl

finwave_wavefront-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: finwave-wavefront
+Version: 0.1.0
+Summary: Official Python client for fetching finwave datasets over the dataset-API handshake.
+Project-URL: Homepage, https://operationalecology.io
+Project-URL: Source, https://github.com/Operational-Ecology/Wavefront
+Project-URL: finwave, https://finwave.io
+Author-email: Alexander Barnhill <alex.c.barnhill@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: conservation,datasets,finwave,photo-identification,wildlife,yolo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: respx>=0.20; extra == 'test'
+Description-Content-Type: text/markdown
+
+# wavefront
+
+The official Python client for **[Finwave](https://finwave.io)** datasets.
+
+Finwave serves frozen, versioned wildlife photo-identification and detector
+datasets behind a small handshake API. `wavefront` turns that into one call.
+
+```bash
+pip install finwave-wavefront
+```
+
+## Quick start
+
+```python
+import wavefront
+
+# the API key is read from $FW_API_TOKEN (or passed as api_key=...)
+ds = wavefront.fetch("a7673931-9810-4c52-9654-1c9b1fafb63d", format="yolo")
+
+print(ds.path)          # extracted, ready to train on
+print(ds.classes)       # ['fluke']
+print(ds.num_images)    # 497
+print(ds.fingerprint)   # content hash — record it next to any model you train
+```
+
+`ds` is path-like, so it drops straight into a trainer:
+
+```python
+from ultralytics import YOLO
+YOLO("yolo11n.pt").train(data=f"{ds.path}/data.yaml")
+```
+
+### Pre-flight without downloading
+
+```python
+m = wavefront.manifest("a7673931-9810-4c52-9654-1c9b1fafb63d")
+print(m.name, m.sample_count, m.available_formats)   # Flukes v1 497 ['Yolo']
+```
+
+### A reusable client
+
+```python
+from wavefront import Client
+client = Client(api_key="...", base_url="https://finwave.io")
+ds = client.fetch(dataset_id, format="yolo", dest="./data/flukes")
+```
+
+### Command line
+
+```bash
+export FW_API_TOKEN=...
+wavefront manifest a7673931-9810-4c52-9654-1c9b1fafb63d
+wavefront fetch    a7673931-9810-4c52-9654-1c9b1fafb63d --format yolo --dest ./data/flukes
+```
+
+## How it works
+
+1. `GET /manifest` — cheap metadata + which export formats are ready.
+2. `GET ?format=…` — a **handshake** that mints a short-lived signed download URL.
+3. Download that URL → a zip → extract → a `Dataset`.
+
+Downloads are **cached by content fingerprint**, so re-fetching a frozen
+version is a no-op. The key needs the dataset-download scope.
+
+## Authentication
+
+Provide the key explicitly (`fetch(..., api_key=...)`) or set **`FW_API_TOKEN`**.
+For compatibility, `WAVEFRONT_API_KEY`, `FINWAVE_DATASET_API_KEY` and
+`DATASET_API_KEY` are also accepted (in that order).
+
+## Errors
+
+All errors subclass `wavefront.WavefrontError`:
+
+| Exception | When |
+|---|---|
+| `AuthError` | key missing / rejected (401/403) |
+| `DatasetNotFoundError` | no such version, or not visible to the key (404) |
+| `FormatNotAvailableError` | the version exists but that export hasn't been generated yet (`.available` lists what is) |
+| `APIError` | any other non-success response |
+
+## License
+
+MIT © Alexander Barnhill / [Operational Ecology](https://operationalecology.io).
+A partnership artifact between finwave and Operational Ecology.

finwave_wavefront-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+wavefront/__init__.py,sha256=TE1Xkoxce6mGQuRHuE44j8s7ZAfFsLEgxwapy2MRjnM,2353
+wavefront/__main__.py,sha256=H4gQQ-7sbs7aNcuH9HkWJF48M14jBnz6FB9HLaYxpmo,3452
+wavefront/_art.py,sha256=rS7Eg2VHcaAw1wzOoLF1OhSbi0XK7j9BywBzDIoaBOc,3768
+wavefront/client.py,sha256=UQU6LP7HuhXJFVNL6lyLBftdUToCSI1CgnDtgLwU8vQ,11619
+wavefront/exceptions.py,sha256=euSj98BqtPwLQjOn8g0vlYMwo650ilnA8KGPrcnv138,1612
+wavefront/models.py,sha256=10XzDm33ND0N6R5LNBqOT9n-8bj9vbvTB46oWOKdPuc,3551
+finwave_wavefront-0.1.0.dist-info/METADATA,sha256=YK2A9-pcAmUM3jsCsQTxX9so9HhmvGq_TNOdAttiaP4,3563
+finwave_wavefront-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+finwave_wavefront-0.1.0.dist-info/entry_points.txt,sha256=ywBYOo2r3QbUAZJTAa9q-u1t3F_y9a60zqYykqahz5k,54
+finwave_wavefront-0.1.0.dist-info/licenses/LICENSE,sha256=HOVL0nFm4EJpu4aftbrw6bElA9TYRozpE8QP5ZEsmjE,1097
+finwave_wavefront-0.1.0.dist-info/RECORD,,

finwave_wavefront-0.1.0.dist-info/WHEEL

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

finwave_wavefront-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wavefront = wavefront.__main__:main

finwave_wavefront-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Barnhill / Operational Ecology
+
+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.

wavefront/__init__.py

@@ -0,0 +1,69 @@
+"""wavefront — the official Python client for finwave datasets.
+
+finwave (https://finwave.io) serves frozen, versioned wildlife photo-ID and
+detector datasets behind a small handshake API. ``wavefront`` turns that into
+one call:
+
+    >>> import wavefront
+    >>> ds = wavefront.fetch("a7673931-9810-4c52-9654-1c9b1fafb63d", format="yolo")
+    >>> ds.path, ds.classes, ds.num_images
+    (PosixPath('.../Yolo-81f97dec8667'), ['fluke'], 497)
+
+The key is read from the ``FW_API_TOKEN`` environment variable (or passed
+explicitly as ``api_key=``); ``WAVEFRONT_API_KEY``, ``FINWAVE_DATASET_API_KEY``
+and ``DATASET_API_KEY`` are also accepted for compatibility. For repeated or
+configured use, construct a :class:`Client`.
+
+Every step logs on the ``wavefront`` logger. The library attaches a
+``NullHandler`` and never configures logging itself — enable output with
+``logging.basicConfig(level=logging.INFO)`` in your application.
+
+Built by Operational Ecology (https://operationalecology.io).
+"""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from .client import API_KEY_ENV, DEFAULT_BASE_URL, Client
+
+logging.getLogger("wavefront").addHandler(logging.NullHandler())
+from .exceptions import (
+    APIError,
+    AuthError,
+    DatasetNotFoundError,
+    FormatNotAvailableError,
+    IntegrityError,
+    WavefrontError,
+)
+from .models import Dataset, Manifest
+
+__version__ = "0.1.0"
+__all__ = [
+    "fetch",
+    "manifest",
+    "Client",
+    "Dataset",
+    "Manifest",
+    "WavefrontError",
+    "AuthError",
+    "DatasetNotFoundError",
+    "FormatNotAvailableError",
+    "IntegrityError",
+    "APIError",
+    "DEFAULT_BASE_URL",
+    "API_KEY_ENV",
+    "__version__",
+]
+
+
+def fetch(dataset_version_id: str, *, format: str = "yolo",
+          api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, **kwargs) -> Dataset:
+    """Fetch + extract a dataset version with a one-off client. See :meth:`Client.fetch`."""
+    return Client(api_key, base_url=base_url).fetch(dataset_version_id, format=format, **kwargs)
+
+
+def manifest(dataset_version_id: str, *,
+             api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL) -> Manifest:
+    """Return a dataset version's manifest with a one-off client. See :meth:`Client.manifest`."""
+    return Client(api_key, base_url=base_url).manifest(dataset_version_id)

wavefront/__main__.py

@@ -0,0 +1,85 @@
+"""Command-line interface: ``wavefront fetch|manifest <id>``."""
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from . import __version__, _art
+from .client import Client
+from .exceptions import WavefrontError
+
+
+def _fmt_bytes(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.0f}{unit}" if unit == "B" else f"{n/1:.0f}{unit}"
+        n /= 1024
+    return f"{n:.0f}B"
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="wavefront", description="Fetch finwave datasets.")
+    p.add_argument("--version", action="version", version=f"wavefront {__version__}")
+    p.add_argument("--api-key", default=None, help="overrides $FW_API_TOKEN")
+    p.add_argument("--base-url", default=None, help="finwave base URL")
+    p.add_argument("-v", "--verbose", action="store_true", help="debug-level logging")
+    p.add_argument("-q", "--quiet", action="store_true", help="warnings and errors only")
+    p.add_argument("--no-art", action="store_true", help="disable the wave animation")
+    sub = p.add_subparsers(dest="cmd", required=False)
+
+    m = sub.add_parser("manifest", help="print a version's metadata + formats")
+    m.add_argument("dataset_version_id")
+
+    f = sub.add_parser("fetch", help="download + extract a dataset version")
+    f.add_argument("dataset_version_id")
+    f.add_argument("--format", default="yolo")
+    f.add_argument("--dest", default=None, help="extract dir (default: cache)")
+    f.add_argument("--force", action="store_true", help="ignore cache")
+
+    args = p.parse_args(argv)
+    level = logging.WARNING if args.quiet else (logging.DEBUG if args.verbose else logging.INFO)
+    logging.basicConfig(level=level, format="%(message)s", stream=sys.stderr)
+    show_art = not (args.no_art or args.quiet)
+    if args.cmd is None:                     # bare `wavefront` → wave + wordmark
+        if show_art:
+            _art.banner()
+        return 0
+    kw = {}
+    if args.base_url:
+        kw["base_url"] = args.base_url
+    try:
+        client = Client(args.api_key, **kw)
+        if args.cmd == "manifest":
+            mf = client.manifest(args.dataset_version_id)
+            print(f"{mf.name} (v{mf.version_number})")
+            print(f"  samples: {mf.sample_count}  annotations: {mf.annotation_count}")
+            print(f"  formats: {mf.available_formats or '(none generated yet)'}")
+            print(f"  fingerprint: {mf.fingerprint}")
+            return 0
+        if args.cmd == "fetch":
+            if show_art:
+                _art.wave()
+            last = [0.0]
+
+            def prog(got, total):
+                pct = f" {100*got/total:.0f}%" if total else ""
+                if got - last[0] >= (1 << 23) or got == total:  # ~8MB steps
+                    print(f"\r  downloading {_fmt_bytes(got)}{pct}", end="", file=sys.stderr)
+                    last[0] = got
+
+            ds = client.fetch(args.dataset_version_id, format=args.format,
+                              dest=args.dest, force=args.force, progress=prog)
+            print("", file=sys.stderr)
+            print(ds.path)
+            print(f"  {ds.num_images} images, {ds.num_labels} labels, classes={ds.classes}",
+                  file=sys.stderr)
+            return 0
+    except WavefrontError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wavefront/_art.py

@@ -0,0 +1,107 @@
+"""A small finwave-blue wave flourish for the terminal. Purely cosmetic.
+
+Animates a travelling, foam-tipped wave in the finwave palette. No-ops on
+non-TTY streams, under ``NO_COLOR``, or for dumb terminals, so it never
+corrupts piped or logged output.
+"""
+from __future__ import annotations
+
+import math
+import os
+import shutil
+import sys
+import time
+from typing import Optional
+
+# finwave palette, deep water → crest (mirrors the logo's blue gradient)
+_GRAD = [
+    (14, 63, 133), (21, 88, 184), (31, 111, 230),
+    (59, 143, 255), (93, 158, 255), (130, 185, 255),
+]
+_FOAM = (224, 238, 255)
+_BLOCKS = " ▁▂▃▄▅▆▇█"
+
+
+def supported(stream) -> bool:
+    return (
+        hasattr(stream, "isatty")
+        and stream.isatty()
+        and not os.environ.get("NO_COLOR")
+        and not os.environ.get("WAVEFRONT_NO_ART")
+        and os.environ.get("TERM", "") not in ("", "dumb")
+    )
+
+
+def _rgb(rgb) -> str:
+    return f"\x1b[38;2;{rgb[0]};{rgb[1]};{rgb[2]}m"
+
+
+def _surface(width: int, rows: int, phase: float) -> list[float]:
+    """Water height in cells (0..rows) per column — two summed travelling waves."""
+    out = []
+    for x in range(width):
+        h = 0.52 + 0.30 * math.sin(x * 0.26 - phase) + 0.14 * math.sin(x * 0.11 + phase * 0.6)
+        out.append(max(0.0, min(1.0, h)) * rows)
+    return out
+
+
+def _render_frame(width: int, rows: int, phase: float) -> str:
+    surf = _surface(width, rows, phase)
+    lines = []
+    for r in range(rows):                       # r = 0 is the top row
+        depth_from_surface = r                   # 0 near crest → lighter
+        line = []
+        for x in range(width):
+            band = surf[x] - (rows - 1 - r)      # cells of water in this row (>1 = full)
+            if band <= 0:
+                line.append(" ")
+                continue
+            crest = band < 1.0                   # the topmost filled cell
+            block = _BLOCKS[min(8, max(1, int(round(band * 8))))] if crest else "█"
+            if crest:
+                color = _FOAM
+            else:
+                gi = min(len(_GRAD) - 1, depth_from_surface)
+                color = _GRAD[len(_GRAD) - 1 - gi] if False else _GRAD[gi]
+            line.append(_rgb(color) + block)
+        lines.append("".join(line) + "\x1b[0m")
+    return "\n".join(lines)
+
+
+def wave(stream=None, *, duration: float = 1.3, fps: int = 30,
+         width: Optional[int] = None, rows: int = 4) -> None:
+    """Play the wave flourish, then leave the terminal clean."""
+    stream = stream or sys.stderr
+    if not supported(stream):
+        return
+    cols = shutil.get_terminal_size((80, 24)).columns
+    w = min(width or cols - 2, 60)
+    frames = max(1, int(duration * fps))
+    stream.write("\x1b[?25l")  # hide cursor
+    try:
+        for f in range(frames):
+            stream.write(_render_frame(w, rows, f / fps * 6.5))
+            if f < frames - 1:
+                stream.write(f"\x1b[{rows - 1}A\r")  # back to top of the wave
+            stream.flush()
+            time.sleep(1.0 / fps)
+        stream.write("\n")
+    finally:
+        stream.write("\x1b[?25h\x1b[0m")  # restore cursor + reset
+        stream.flush()
+
+
+def banner(stream=None) -> None:
+    """A one-shot wave + wordmark, used by the bare ``wavefront`` command."""
+    from . import __version__
+    stream = stream or sys.stderr
+    wave(stream, duration=1.1)
+    if supported(stream):
+        stream.write(_rgb(_GRAD[3]) + "  wavefront " + _rgb(_GRAD[5])
+                     + f"v{__version__}\x1b[0m  " + "\x1b[2mfinwave datasets, one call\x1b[0m\n")
+    else:
+        stream.write(f"wavefront v{__version__} — finwave datasets, one call\n")
+
+
+if __name__ == "__main__":  # quick visual check: `python -m wavefront._art`
+    wave(sys.stdout, duration=3.0)

wavefront/client.py

@@ -0,0 +1,277 @@
+"""The finwave dataset client.
+
+The flow mirrors the finwave dataset API exactly:
+
+1. ``GET /api/datasets-api/{id}/manifest``  → cheap metadata + available formats
+2. ``GET /api/datasets-api/{id}?format=...`` → a *handshake* that mints a short-
+   lived signed download URL (no bytes yet)
+3. download the signed URL → a zip → extract → a :class:`~wavefront.models.Dataset`
+
+Authentication is the ``X-API-KEY`` header; the key needs the dataset-download
+scope. Downloads are cached by content fingerprint, so a repeated fetch of the
+same frozen version is a no-op.
+
+Every step emits an ``INFO`` log line on the ``wavefront`` logger so a caller
+can see exactly what happened; the library installs a ``NullHandler`` and never
+configures logging itself.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import tempfile
+import time
+import zipfile
+from pathlib import Path
+from typing import Callable, Optional
+
+import httpx
+
+from .exceptions import (
+    APIError,
+    AuthError,
+    DatasetNotFoundError,
+    FormatNotAvailableError,
+)
+from .models import Dataset, Manifest
+
+log = logging.getLogger("wavefront")
+
+DEFAULT_BASE_URL = "https://finwave.io"
+#: Environment variables consulted for the API key, in order. ``FW_API_TOKEN``
+#: is the canonical name; the rest are accepted for compatibility.
+API_KEY_ENV = ("FW_API_TOKEN", "WAVEFRONT_API_KEY", "FINWAVE_DATASET_API_KEY", "DATASET_API_KEY")
+_FORMAT_ALIASES = {"yolo": "Yolo", "coco": "Coco", "pascalvoc": "PascalVoc", "voc": "PascalVoc"}
+_COMPLETE_MARKER = ".wavefront-complete"
+
+
+def _mask(key: str) -> str:
+    """A safe-to-log fingerprint of a secret: never the secret itself."""
+    return f"{key[:3]}…{key[-2:]} ({len(key)} chars)" if len(key) >= 6 else "set"
+
+
+def _resolve_key(api_key: Optional[str]) -> tuple[str, str]:
+    """Return (key, source) — source is 'argument' or the env var name."""
+    if api_key:
+        return api_key, "argument"
+    for name in API_KEY_ENV:
+        v = os.environ.get(name)
+        if v:
+            return v, name
+    raise AuthError(
+        "No API key provided. Pass api_key=... or set the FW_API_TOKEN "
+        "environment variable (also accepted: " + ", ".join(API_KEY_ENV[1:]) + ")."
+    )
+
+
+def _canonical_format(fmt: str) -> str:
+    return _FORMAT_ALIASES.get(fmt.lower(), fmt)
+
+
+def _default_cache_root() -> Path:
+    root = os.environ.get("WAVEFRONT_CACHE")
+    if root:
+        return Path(root)
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
+    return Path(base) / "wavefront"
+
+
+def _human_bytes(n: Optional[int]) -> str:
+    if not n:
+        return "?"
+    f = float(n)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if f < 1024 or unit == "TB":
+            return f"{f:.0f} {unit}" if unit == "B" else f"{f:.1f} {unit}"
+        f /= 1024
+    return f"{f:.1f} TB"
+
+
+class Client:
+    """A reusable finwave dataset client.
+
+    Parameters
+    ----------
+    api_key:
+        Dataset-download-scoped key. If omitted, the ``FW_API_TOKEN`` environment
+        variable is used (also accepted: ``WAVEFRONT_API_KEY``,
+        ``FINWAVE_DATASET_API_KEY``, ``DATASET_API_KEY``).
+    base_url:
+        finwave base URL (default ``https://finwave.io``).
+    timeout:
+        Per-request timeout in seconds for the API calls (the large artifact
+        download uses a longer, separate timeout).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key, source = _resolve_key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        log.info("wavefront client ready: base_url=%s, key from %s [%s]",
+                 self.base_url, source, _mask(self.api_key))
+
+    # ── low-level ────────────────────────────────────────────────────────────
+    def _get(self, path: str, **kwargs) -> httpx.Response:
+        url = f"{self.base_url}/api/datasets-api/{path}"
+        log.debug("GET %s %s", url, kwargs.get("params", ""))
+        try:
+            resp = httpx.get(url, headers={"X-API-KEY": self.api_key},
+                             timeout=self.timeout, **kwargs)
+        except httpx.HTTPError as e:  # network-level
+            log.error("request to %s failed: %s", url, e)
+            raise APIError(f"request to {url} failed: {e}") from e
+        log.debug("→ HTTP %d (%s)", resp.status_code, _human_bytes(len(resp.content)))
+        if resp.status_code in (401, 403):
+            raise AuthError(
+                "API key rejected (HTTP %d) — check the key and that it has the "
+                "dataset-download scope." % resp.status_code
+            )
+        return resp
+
+    @staticmethod
+    def _error_payload(resp: httpx.Response) -> dict:
+        try:
+            return resp.json()
+        except Exception:
+            return {}
+
+    # ── public API ───────────────────────────────────────────────────────────
+    def manifest(self, dataset_version_id: str) -> Manifest:
+        """Return version metadata + available export formats (no download)."""
+        log.info("manifest: requesting %s", dataset_version_id)
+        resp = self._get(f"{dataset_version_id}/manifest")
+        if resp.status_code == 404:
+            raise DatasetNotFoundError(
+                f"dataset version {dataset_version_id!r} not found (or not visible to this key)"
+            )
+        if resp.status_code != 200:
+            raise APIError("manifest request failed", status_code=resp.status_code,
+                           payload=self._error_payload(resp))
+        m = Manifest.from_response(resp.json())
+        log.info("manifest: '%s' v%d — %d samples, %d annotations, formats=%s",
+                 m.name, m.version_number, m.sample_count, m.annotation_count,
+                 m.available_formats or "none yet")
+        return m
+
+    def fetch(
+        self,
+        dataset_version_id: str,
+        *,
+        format: str = "yolo",
+        dest: Optional[os.PathLike] = None,
+        cache: bool = True,
+        force: bool = False,
+        progress: Optional[Callable[[int, Optional[int]], None]] = None,
+    ) -> Dataset:
+        """Fetch + extract a dataset version, returning a :class:`Dataset`.
+
+        Parameters
+        ----------
+        format:
+            Export format, case-insensitive (``"yolo"`` by default).
+        dest:
+            Directory to extract into. Defaults to the fingerprint-keyed cache.
+        cache:
+            Reuse a previously-completed download of the same frozen fingerprint.
+        force:
+            Re-download even if a cached copy exists.
+        progress:
+            Optional callback ``(bytes_downloaded, total_or_None)`` for the
+            artifact download.
+        """
+        fmt = _canonical_format(format)
+        log.info("fetch: %s (format=%s)", dataset_version_id, fmt)
+        m = self.manifest(dataset_version_id)
+        if not m.has_format(fmt):
+            raise FormatNotAvailableError(
+                f"format {fmt!r} is not available for '{m.name}'. "
+                f"Available: {m.available_formats or 'none yet — an export must be generated'}.",
+                available=m.available_formats,
+            )
+
+        if dest is not None:
+            out = Path(dest)
+        else:
+            out = _default_cache_root() / f"{dataset_version_id}" / f"{fmt}-{m.fingerprint[:12]}"
+
+        marker = out / _COMPLETE_MARKER
+        if cache and not force and marker.exists() and marker.read_text().strip() == m.fingerprint:
+            ds = Dataset.from_extracted(root=out, manifest=m, fmt=fmt)
+            log.info("fetch: cache hit (fingerprint %s) → %s [%d images]",
+                     m.fingerprint[:12], out, ds.num_images)
+            return ds
+
+        log.info("fetch: requesting download handshake…")
+        download_url = self._handshake(dataset_version_id, fmt)
+        out.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
+            tmp_path = Path(tmp.name)
+        try:
+            self._download(download_url, tmp_path, progress=progress)
+            log.info("fetch: extracting to %s", out)
+            for child in out.iterdir():
+                if child.name == _COMPLETE_MARKER:
+                    continue
+                shutil.rmtree(child) if child.is_dir() else child.unlink()
+            with zipfile.ZipFile(tmp_path) as zf:
+                zf.extractall(out)
+        finally:
+            tmp_path.unlink(missing_ok=True)
+        marker.write_text(m.fingerprint)
+        ds = Dataset.from_extracted(root=out, manifest=m, fmt=fmt)
+        log.info("fetch: ready → %s [%d images, %d labels, classes=%s]",
+                 out, ds.num_images, ds.num_labels, ds.classes)
+        return ds
+
+    # ── internals ────────────────────────────────────────────────────────────
+    def _handshake(self, dataset_version_id: str, fmt: str) -> str:
+        resp = self._get(dataset_version_id, params={"format": fmt})
+        if resp.status_code == 404:
+            payload = self._error_payload(resp)
+            detail = (payload.get("detail") or "").lower()
+            if "format" in detail:
+                raise FormatNotAvailableError(
+                    f"format {fmt!r} has not been produced for this version yet "
+                    "(exports are generated separately from freezing)."
+                )
+            raise DatasetNotFoundError(f"dataset version {dataset_version_id!r} not found")
+        if resp.status_code != 200:
+            raise APIError("handshake failed", status_code=resp.status_code,
+                           payload=self._error_payload(resp))
+        body = resp.json()
+        url = body.get("downloadUrl")
+        if not url:
+            raise APIError("handshake response had no downloadUrl",
+                           status_code=resp.status_code, payload=body)
+        log.info("handshake: signed URL minted (expires %s)",
+                 body.get("sasExpiresAt", "soon"))
+        return url
+
+    def _download(self, url: str, dest: Path, *,
+                  progress: Optional[Callable[[int, Optional[int]], None]] = None) -> None:
+        # The download URL is a pre-signed object URL — no API key, long timeout.
+        t0 = time.monotonic()
+        with httpx.stream("GET", url, timeout=httpx.Timeout(None, connect=30.0),
+                          follow_redirects=True) as resp:
+            if resp.status_code != 200:
+                raise APIError(f"artifact download failed (HTTP {resp.status_code})",
+                               status_code=resp.status_code)
+            total = int(resp.headers.get("Content-Length", 0)) or None
+            log.info("download: %s …", _human_bytes(total))
+            got = 0
+            with open(dest, "wb") as f:
+                for chunk in resp.iter_bytes(1 << 20):
+                    f.write(chunk)
+                    got += len(chunk)
+                    if progress is not None:
+                        progress(got, total)
+        dt = time.monotonic() - t0
+        rate = got / dt / (1 << 20) if dt > 0 else 0
+        log.info("download: %s in %.1fs (%.0f MB/s)", _human_bytes(got), dt, rate)

wavefront/exceptions.py

@@ -0,0 +1,49 @@
+"""Exceptions raised by wavefront.
+
+All inherit from :class:`WavefrontError`, so callers can catch the whole family
+with a single ``except WavefrontError``.
+"""
+from __future__ import annotations
+
+
+class WavefrontError(Exception):
+    """Base class for all wavefront errors."""
+
+
+class AuthError(WavefrontError):
+    """The API key was missing, malformed, or rejected (HTTP 401/403)."""
+
+
+class DatasetNotFoundError(WavefrontError):
+    """No dataset version with the given id is visible to this key (HTTP 404)."""
+
+
+class FormatNotAvailableError(WavefrontError):
+    """The requested export format has not been produced for this version yet.
+
+    The dataset exists but ``availableFormats`` does not include the requested
+    format — an admin must generate the export first (it is not produced on
+    freeze). :attr:`available` lists what *is* ready.
+    """
+
+    def __init__(self, message: str, *, available: list[str] | None = None) -> None:
+        super().__init__(message)
+        self.available = available or []
+
+
+class IntegrityError(WavefrontError):
+    """A downloaded artifact did not match the fingerprint the server declared."""
+
+
+class APIError(WavefrontError):
+    """An unexpected, non-success response from the finwave API.
+
+    :attr:`status_code` is the HTTP status; :attr:`payload` is the parsed error
+    body when the server returned one.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None,
+                 payload: dict | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload or {}

wavefront/models.py

@@ -0,0 +1,111 @@
+"""Typed views over the finwave dataset-API responses and the local result.
+
+These are thin, read-only dataclasses; the wire shapes they mirror are the
+``/manifest`` and handshake responses of ``/api/datasets-api/{id}``.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+def _parse_dt(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True)
+class Manifest:
+    """Cheap pre-flight metadata for a dataset version (no download minted)."""
+
+    dataset_version_id: str
+    parent_dataset_id: str
+    name: str
+    version_number: int
+    fingerprint: str
+    sample_count: int
+    annotation_count: int
+    includes_negatives: bool
+    available_formats: list[str]
+    frozen_at: Optional[datetime] = None
+    raw: dict = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_response(cls, d: dict) -> "Manifest":
+        return cls(
+            dataset_version_id=d.get("datasetVersionId", ""),
+            parent_dataset_id=d.get("parentDatasetId", ""),
+            name=d.get("name", ""),
+            version_number=int(d.get("versionNumber", 0) or 0),
+            fingerprint=d.get("fingerprint", ""),
+            sample_count=int(d.get("sampleCount", 0) or 0),
+            annotation_count=int(d.get("annotationCount", 0) or 0),
+            includes_negatives=bool(d.get("includesNegatives", False)),
+            available_formats=list(d.get("availableFormats", []) or []),
+            frozen_at=_parse_dt(d.get("frozenAt")),
+            raw=d,
+        )
+
+    def has_format(self, fmt: str) -> bool:
+        return fmt.lower() in {f.lower() for f in self.available_formats}
+
+
+@dataclass(frozen=True)
+class Dataset:
+    """A fetched, extracted dataset on local disk.
+
+    ``fingerprint`` is the server's content hash for this exact version — record
+    it alongside any model you train so the data is traceable.
+    """
+
+    id: str
+    name: str
+    version: int
+    fmt: str
+    fingerprint: str
+    path: Path
+    classes: list[str] = field(default_factory=list)
+    num_images: int = 0
+    num_labels: int = 0
+
+    def __fspath__(self) -> str:        # usable directly as a path
+        return str(self.path)
+
+    def __str__(self) -> str:
+        return str(self.path)
+
+    @property
+    def images_dir(self) -> Path:
+        return self.path / "images"
+
+    @property
+    def labels_dir(self) -> Path:
+        return self.path / "labels"
+
+    @classmethod
+    def from_extracted(cls, *, root: Path, manifest: Manifest, fmt: str) -> "Dataset":
+        exts = (".jpg", ".jpeg", ".png", ".bmp", ".tif", ".tiff", ".webp")
+        imgs = [p for p in root.rglob("*") if p.suffix.lower() in exts]
+        labels = [p for p in root.rglob("*.txt") if "label" in str(p.parent).lower()]
+        classes: list[str] = []
+        cf = next((p for p in root.rglob("classes.txt")), None)
+        if cf is not None:
+            classes = [ln.strip() for ln in cf.read_text().splitlines() if ln.strip()]
+        return cls(
+            id=manifest.dataset_version_id,
+            name=manifest.name,
+            version=manifest.version_number,
+            fmt=fmt,
+            fingerprint=manifest.fingerprint,
+            path=root,
+            classes=classes,
+            num_images=len(imgs),
+            num_labels=len(labels),
+        )