babon 0.1.0__py3-none-any.whl

babon/__init__.py

@@ -0,0 +1,267 @@
+"""Babon — kinematics-as-a-service client for Python.
+
+    pip install babon
+
+    from babon import Babon
+    Babon("bk_...").analyze("trial.mp4").save("out.zip")
+
+That's it.
+
+Internally this wraps `api.babon.eu/v1/*` with `requests`. Idempotency,
+polling, error envelope decoding, file handling: all handled. Customer
+sees one class and three methods.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Iterator, Optional, Union
+
+import requests
+
+
+__all__ = [
+    "Babon",
+    "Run",
+    "RunBatch",
+    "BabonError",
+    "BabonAuthError",
+    "BabonQuotaExceeded",
+    "BabonInvalidVideo",
+    "BabonInvalidLabel",
+    "BabonRunFailed",
+    "BabonTimeout",
+]
+
+
+DEFAULT_BASE_URL = "https://api.babon.eu"
+DEFAULT_POLL_INTERVAL_S = 30
+DEFAULT_WAIT_TIMEOUT_S = 60 * 60 * 6  # 6 hours, covers an overnight batch
+
+
+# ─────────────────── exceptions ───────────────────
+
+class BabonError(Exception):
+    """Base class for everything the client raises."""
+
+    def __init__(self, message: str, *, code: str = "", request_id: str = ""):
+        super().__init__(message)
+        self.code = code
+        self.request_id = request_id
+
+
+class BabonAuthError(BabonError): pass
+class BabonQuotaExceeded(BabonError): pass
+class BabonInvalidVideo(BabonError): pass
+class BabonInvalidLabel(BabonError): pass
+class BabonRunFailed(BabonError): pass
+class BabonTimeout(BabonError): pass
+
+
+_CODE_TO_EXC: dict[str, type[BabonError]] = {
+    "MISSING_AUTH":      BabonAuthError,
+    "INVALID_AUTH":      BabonAuthError,
+    "WRONG_ENVIRONMENT": BabonAuthError,
+    "DPA_NOT_ACCEPTED":  BabonAuthError,
+    "QUOTA_EXCEEDED":    BabonQuotaExceeded,
+    "CONCURRENT_LIMIT":  BabonQuotaExceeded,
+    "RATE_LIMITED":      BabonQuotaExceeded,
+    "INVALID_VIDEO":     BabonInvalidVideo,
+    "VIDEO_REQUIRED":    BabonInvalidVideo,
+    "INVALID_LABEL":     BabonInvalidLabel,
+}
+
+
+def _raise_for_envelope(response: requests.Response) -> None:
+    if response.ok:
+        return
+    try:
+        body = response.json()
+    except Exception:
+        raise BabonError(f"HTTP {response.status_code}: {response.text[:200]}")
+    err = (body or {}).get("error") or {}
+    code = err.get("code", "")
+    message = err.get("message", f"HTTP {response.status_code}")
+    request_id = err.get("request_id", "")
+    exc_cls = _CODE_TO_EXC.get(code, BabonError)
+    raise exc_cls(message, code=code, request_id=request_id)
+
+
+def _auto_idempotency_key(file_path: Path, key: str) -> str:
+    """Stable hash of (api key + filename + size + first 4 KB of file).
+
+    First 4 KB is enough to discriminate distinct uploads without
+    re-reading the whole file. Same input, same upload → same idem key →
+    server replays the prior response.
+    """
+    h = hashlib.sha256()
+    h.update(key.encode())
+    h.update(b"\x00")
+    h.update(str(file_path).encode())
+    h.update(b"\x00")
+    h.update(str(file_path.stat().st_size).encode())
+    h.update(b"\x00")
+    with open(file_path, "rb") as f:
+        h.update(f.read(4096))
+    return h.hexdigest()
+
+
+# ─────────────────── public surface ───────────────────
+
+@dataclass
+class Run:
+    """A submitted analysis. Returned from `Babon.analyze(...)`.
+
+    Methods you care about:
+      .wait()                          block until the run terminates
+      .save(path)                      block + download the bundle.zip
+      .data                            block + return clinical_report.json as a dict
+      .id, .status                     introspection
+    """
+
+    id: str
+    _client: "Babon"
+    _status: str = "queued"
+
+    @property
+    def status(self) -> str:
+        return self._status
+
+    def refresh(self) -> "Run":
+        body = self._client._get(f"/api/v1/runs/{self.id}")
+        self._status = body.get("status", "unknown")
+        return self
+
+    def wait(
+        self,
+        *,
+        timeout_s: int = DEFAULT_WAIT_TIMEOUT_S,
+        poll_every_s: int = DEFAULT_POLL_INTERVAL_S,
+    ) -> "Run":
+        """Block until the run reaches a terminal state."""
+        started = time.monotonic()
+        while True:
+            self.refresh()
+            if self._status == "completed":
+                return self
+            if self._status == "failed":
+                raise BabonRunFailed(f"run {self.id} failed", code="RUN_FAILED")
+            if time.monotonic() - started > timeout_s:
+                raise BabonTimeout(
+                    f"run {self.id} did not complete within {timeout_s}s "
+                    f"(last status: {self._status})",
+                    code="TIMEOUT",
+                )
+            time.sleep(poll_every_s)
+
+    def save(self, path: Union[str, os.PathLike], *, include_preview: bool = False) -> Path:
+        """Wait for completion and write the bundle to `path`."""
+        self.wait()
+        url = f"/api/v1/runs/{self.id}/bundle.zip"
+        if include_preview:
+            url += "?include_preview=true"
+        out = Path(path)
+        out.write_bytes(self._client._get_bytes(url))
+        return out
+
+    @property
+    def data(self) -> dict:
+        """Wait for completion and return clinical_report.json as a dict."""
+        self.wait()
+        body = self._client._get_bytes(f"/api/v1/runs/{self.id}/files/clinical_report.json")
+        import json as _json
+        return _json.loads(body)
+
+
+@dataclass
+class RunBatch:
+    runs: list[Run]
+
+    def __iter__(self) -> Iterator[Run]:
+        return iter(self.runs)
+
+    def __len__(self) -> int:
+        return len(self.runs)
+
+    def wait(self, **kwargs) -> "RunBatch":
+        for run in self.runs:
+            run.wait(**kwargs)
+        return self
+
+    def save(self, directory: Union[str, os.PathLike], *, include_preview: bool = False) -> list[Path]:
+        out_dir = Path(directory)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        paths = []
+        for run in self.runs:
+            paths.append(run.save(out_dir / f"{run.id}.zip", include_preview=include_preview))
+        return paths
+
+
+class Babon:
+    """Babon client. One key per organisation.
+
+    Babon("bk_...").analyze("trial.mp4").save("out.zip")
+    """
+
+    def __init__(self, key: str, *, base_url: str = DEFAULT_BASE_URL, timeout_s: int = 600):
+        if not key:
+            raise BabonAuthError("api key is required", code="MISSING_AUTH")
+        self._key = key
+        self._base_url = base_url.rstrip("/")
+        self._timeout_s = timeout_s
+
+    # public surface
+    def analyze(
+        self,
+        video: Union[str, os.PathLike, Iterable[Union[str, os.PathLike]]],
+        *,
+        label: Optional[str] = None,
+    ) -> Union[Run, RunBatch]:
+        """Submit one video or a list. Returns a Run or a RunBatch.
+
+        analyze("trial.mp4")                       -> Run
+        analyze(["a.mp4", "b.mp4"])                -> RunBatch
+        analyze("trial.mp4", label="cohort-3")     -> Run with custom label
+        """
+        if isinstance(video, (str, os.PathLike)):
+            return self._submit_one(Path(video), label=label)
+        return RunBatch([self._submit_one(Path(v), label=label) for v in video])
+
+    # internals
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self._key}"}
+
+    def _submit_one(self, path: Path, *, label: Optional[str]) -> Run:
+        if not path.is_file():
+            raise FileNotFoundError(f"video not found: {path}")
+        headers = self._headers()
+        headers["Idempotency-Key"] = _auto_idempotency_key(path, self._key)
+        data: dict = {}
+        if label:
+            data["label"] = label
+        with open(path, "rb") as f:
+            files = {"video": (path.name, f, "application/octet-stream")}
+            resp = requests.post(
+                f"{self._base_url}/api/v1/runs",
+                headers=headers,
+                data=data,
+                files=files,
+                timeout=self._timeout_s,
+            )
+        _raise_for_envelope(resp)
+        body = resp.json()
+        return Run(id=body["run_id"], _client=self, _status=body.get("status", "queued"))
+
+    def _get(self, path: str) -> dict:
+        resp = requests.get(f"{self._base_url}{path}", headers=self._headers(), timeout=self._timeout_s)
+        _raise_for_envelope(resp)
+        return resp.json()
+
+    def _get_bytes(self, path: str) -> bytes:
+        resp = requests.get(f"{self._base_url}{path}", headers=self._headers(), timeout=self._timeout_s)
+        _raise_for_envelope(resp)
+        return resp.content

babon/cli.py

@@ -0,0 +1,147 @@
+"""Babon CLI — `babon <command>`.
+
+Installed as a console_scripts entry point, so `pip install babon` puts
+a `babon` binary on the user's PATH. The customer never writes glue
+scripts; they just run:
+
+    babon analyze trial.mp4
+    babon analyze ./videos/
+    babon status <run_id>
+    babon download <run_id>
+    babon resume
+
+The key comes from `BABON_KEY` in the environment (or `--key`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from babon import Babon, Run, BabonError
+
+
+def _key(args) -> str:
+    key = args.key or os.environ.get("BABON_KEY", "")
+    if not key:
+        print("set BABON_KEY=bk_... or pass --key", file=sys.stderr)
+        sys.exit(2)
+    return key
+
+
+def _collect_videos(target: Path) -> list[Path]:
+    if target.is_file():
+        return [target]
+    if target.is_dir():
+        return sorted(p for p in target.glob("*.mp4") if p.is_file())
+    print(f"not found: {target}", file=sys.stderr)
+    sys.exit(2)
+
+
+def cmd_analyze(args) -> int:
+    bb = Babon(_key(args))
+    videos = _collect_videos(Path(args.path))
+    if not videos:
+        print(f"no .mp4 files in {args.path}", file=sys.stderr)
+        return 2
+
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    print(f"submitting {len(videos)} video(s)...", flush=True)
+    runs = bb.analyze([str(v) for v in videos], label=args.label)
+    if isinstance(runs, Run):
+        runs_list = [runs]
+    else:
+        runs_list = list(runs)
+
+    for run, video in zip(runs_list, videos):
+        print(f"  {video.name:30s} -> {run.id}", flush=True)
+
+    print("waiting for completion, then downloading...", flush=True)
+    for run, video in zip(runs_list, videos):
+        out_path = out_dir / f"{video.stem}_{run.id}.zip"
+        print(f"  {run.id}: polling ...", flush=True, end="")
+        run.save(str(out_path), include_preview=args.include_preview)
+        size_mb = out_path.stat().st_size / 1e6
+        print(f" saved {out_path.name} ({size_mb:.1f} MB)", flush=True)
+    return 0
+
+
+def cmd_status(args) -> int:
+    bb = Babon(_key(args))
+    body = bb._get(f"/api/v1/runs/{args.run_id}")
+    for k in ("run_id", "status", "stage", "progress", "created_at", "last_update"):
+        if k in body:
+            print(f"{k:14s} {body[k]}")
+    if body.get("status") == "failed" and body.get("error"):
+        print(f"error          {body['error']}")
+    return 0
+
+
+def cmd_download(args) -> int:
+    bb = Babon(_key(args))
+    out = Path(args.out or f"{args.run_id}.zip")
+    run = Run(id=args.run_id, _client=bb)
+    run.save(str(out), include_preview=args.include_preview)
+    print(f"saved {out} ({out.stat().st_size / 1e6:.1f} MB)")
+    return 0
+
+
+def cmd_resume(args) -> int:
+    """Pick up any non-terminal runs for this tenant and wait+download them.
+
+    Reads the usage endpoint to find the org id, then walks recent
+    submitted runs. For the pilot tier with low volume this is fine; a
+    cohort-volume tenant would page through /v1/runs (list endpoint, to
+    be added) instead.
+    """
+    print("usage endpoint provides totals but not run ids; ask Babon for the list endpoint", file=sys.stderr)
+    return 3
+
+
+def _add_key(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--key", help="API key (or set BABON_KEY env)")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="babon")
+    _add_key(parser)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_analyze = sub.add_parser("analyze", help="submit one video or all .mp4 in a directory, wait, download")
+    _add_key(p_analyze)
+    p_analyze.add_argument("path", help="path to a .mp4 file or a directory of them")
+    p_analyze.add_argument("--out", default="./out", help="output directory (default ./out)")
+    p_analyze.add_argument("--label", default=None, help="optional opaque identifier")
+    p_analyze.add_argument("--include-preview", action="store_true", help="include rendered preview mp4 in the bundle")
+    p_analyze.set_defaults(fn=cmd_analyze)
+
+    p_status = sub.add_parser("status", help="print lifecycle state for one run")
+    _add_key(p_status)
+    p_status.add_argument("run_id")
+    p_status.set_defaults(fn=cmd_status)
+
+    p_download = sub.add_parser("download", help="download the bundle for a completed run")
+    _add_key(p_download)
+    p_download.add_argument("run_id")
+    p_download.add_argument("--out", default=None, help="output file (default <run_id>.zip)")
+    p_download.add_argument("--include-preview", action="store_true")
+    p_download.set_defaults(fn=cmd_download)
+
+    p_resume = sub.add_parser("resume", help="wait + download any in-flight runs for this tenant")
+    _add_key(p_resume)
+    p_resume.set_defaults(fn=cmd_resume)
+
+    args = parser.parse_args()
+    try:
+        return args.fn(args)
+    except BabonError as exc:
+        print(f"ERROR: {type(exc).__name__}: {exc} (code={exc.code} req={exc.request_id})",
+              file=sys.stderr)
+        return 4
+
+
+if __name__ == "__main__":
+    sys.exit(main())

babon-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: babon
+Version: 0.1.0
+Summary: Babon kinematics-as-a-service client. Video in, movement data out.
+Author-email: "Babon Innovations B.V." <daan@babon.eu>
+License: MIT
+Project-URL: Homepage, https://babon.eu
+Project-URL: Documentation, https://api.babon.eu/api/v1/docs
+Keywords: biomechanics,kinematics,gait,video-analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# babon
+
+Kinematics-as-a-service client. Video in, movement data out.
+
+```bash
+pip install babon
+```
+
+```python
+from babon import Babon
+
+Babon("bk_...").analyze("trial.mp4").save("out.zip")
+```
+
+That's it.
+
+## A bit more
+
+```python
+from babon import Babon
+
+bb = Babon("bk_...")
+
+# get the clinical_report.json dict directly
+report = bb.analyze("trial.mp4").data
+print(report["gait_parameters"]["gait_velocity_m_s"])
+
+# batch
+bb.analyze(["a.mp4", "b.mp4", "c.mp4"]).save("./results/")
+
+# tag with your own identifier
+bb.analyze("trial.mp4", label="cohort-3-day-7").save("out.zip")
+```
+
+## What's in the bundle
+
+`clinical_report.json` (gait params, GRF, symmetry), 14 per-joint angle CSVs (ISB convention), raw rotation matrices, 3D joint positions, `bodymodel.npz`, `grf_waveform.json`, `manifest.json` with SHA-256 per file.
+
+## Errors
+
+The client raises typed exceptions:
+
+- `BabonAuthError` — bad key, wrong environment, DPA not accepted.
+- `BabonQuotaExceeded` — monthly limit, concurrent limit, or rate-limited.
+- `BabonInvalidVideo` — file is not a recognised container.
+- `BabonInvalidLabel` — label looks like a real name (ADR-0002).
+- `BabonRunFailed` — pipeline failed.
+- `BabonTimeout` — `wait()` exceeded its timeout.
+
+All carry `.code` (the API error code) and `.request_id` (the support handle).
+
+## What we are and are not
+
+- Measurement only. Output is kinematics; clinical interpretation is yours.
+- EU-cloud (Scaleway fr-par). Videos never leave the EU.
+- Don't put real patient names in `label` or in your filenames. We reject name-shaped labels server-side.
+
+## Contact
+
+daan@babon.eu — onboarding, quota, bugs.

babon-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+babon/__init__.py,sha256=UJrkLXZnto2of7m1Sk7BrmkeObCL6Adijjm9bmybDFw,8675
+babon/cli.py,sha256=TtGUQKbrWB99vddStBuUTObgb9TYQDPxVQYXfZV2-ac,5035
+babon-0.1.0.dist-info/METADATA,sha256=P0uBUSL-gqOjfzdpwmQDYF66_opkReQdDntdo0pLcak,2352
+babon-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+babon-0.1.0.dist-info/entry_points.txt,sha256=5Anw46ZXM1FfdNrJp7DXBzMEh1vB3XkyNGYGXRv8pF0,41
+babon-0.1.0.dist-info/top_level.txt,sha256=_cCy65oLW-aQqSN4vIkmaEppHT5ozZSb1QurDAtl1qQ,6
+babon-0.1.0.dist-info/RECORD,,

babon-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

babon-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+babon = babon.cli:main

babon-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+babon