finwave-wavefront 0.1.0__tar.gz

finwave_wavefront-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store

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

finwave_wavefront-0.1.0/PKG-INFO

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

@@ -0,0 +1,57 @@
+# PROTOCOL — wavefront
+
+Decision log for the finwave dataset client. Governance: [`../CLAUDE.md`](../CLAUDE.md).
+
+## Mission
+
+### One-line — the official, public Python client for fetching finwave datasets
+Status: Committed — 2026-06-21
+finwave already exposes a dataset handshake API (`/api/datasets-api/{id}`); every
+consumer was re-implementing the manifest → handshake → SAS-download → unzip
+dance by hand. `wavefront` is the single, supported way to do it. It is
+OpEco's **first public** project (PyPI + public GitHub) and a deliberate
+finwave × Operational Ecology partnership artifact, both authored by AB.
+
+## Scope
+
+### v1 fetches frozen versions in declared export formats; it does not create them
+Status: Committed — 2026-06-21
+The client is read/download only. Generating an export (e.g. producing the YOLO
+bundle for a frozen version) is an admin action on the Hub and is out of scope —
+hence `FormatNotAvailableError` carries `.available` rather than trying to
+trigger generation. The dataset-API key is download-scoped only.
+
+## Design
+
+### Caching is keyed by the server's content fingerprint, not by id alone
+Status: Committed — 2026-06-21
+Versions are frozen, so a fingerprint pins exact bytes. A completed extraction
+writes a `.wavefront-complete` marker containing the fingerprint; a later fetch
+with a matching marker is a no-op. This makes `fetch` idempotent and cheap to
+call in a training loop without a manual "already downloaded?" guard.
+
+### `Dataset.fingerprint` is surfaced as first-class provenance
+Status: Committed — 2026-06-21
+Every fetched dataset exposes the version fingerprint so a downstream training
+run can record exactly which data produced a model (aligns with OpEco Rule 2,
+source-code/data consistency). The client does not recompute the hash
+client-side (the algorithm is server-owned); it carries the declared one.
+
+### API-key precedence: explicit arg → `FW_API_TOKEN` → `WAVEFRONT_API_KEY` → `FINWAVE_DATASET_API_KEY` → `DATASET_API_KEY`
+Status: Committed — 2026-06-21
+`FW_API_TOKEN` is the canonical name; the rest are accepted so existing
+finwave/finprint workspace environments keep working unchanged.
+
+## Deferred
+
+### Streaming-to-disk integrity check beyond fingerprint consistency
+Status: Open — 2026-06-21
+The handshake and manifest fingerprints are checked for consistency, but the
+downloaded bytes are not independently re-hashed against a per-file digest (the
+export bundle does not yet ship one). Revisit if the Hub starts emitting
+per-artifact `sha256` so `IntegrityError` can be raised on a real mismatch.
+
+### Additional export formats (COCO, PascalVoc)
+Status: Parked — 2026-06-21
+Format aliases are mapped, but only YOLO is produced by the Hub in v1. The
+client already accepts any format string and lets the server decide.

finwave_wavefront-0.1.0/README.md

@@ -0,0 +1,85 @@
+# 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/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "finwave-wavefront"
+version = "0.1.0"
+description = "Official Python client for fetching finwave datasets over the dataset-API handshake."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Alexander Barnhill", email = "alex.c.barnhill@gmail.com" }]
+keywords = ["finwave", "wildlife", "photo-identification", "datasets", "conservation", "yolo"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://operationalecology.io"
+Source = "https://github.com/Operational-Ecology/Wavefront"
+"finwave" = "https://finwave.io"
+
+[project.optional-dependencies]
+test = ["pytest>=7", "respx>=0.20"]
+
+[project.scripts]
+wavefront = "wavefront.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wavefront"]

finwave_wavefront-0.1.0/src/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)

finwave_wavefront-0.1.0/src/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())

finwave_wavefront-0.1.0/src/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)