nocturne-client 1.0.0__tar.gz

nocturne_client-1.0.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: nocturne-client
+Version: 1.0.0
+Summary: Python client for the Nocturne bioacoustic species classifier (by Stratus Labs).
+Author: Stratus Labs
+License: Apache-2.0
+Project-URL: Homepage, https://nocturne.runstratus.com
+Project-URL: Model, https://huggingface.co/stratus-labs/nocturne-v1-teacher
+Project-URL: Source, https://github.com/stratus-labs/nocturne-client
+Keywords: bioacoustics,audio,classification,insects,amphibians,ecology
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# nocturne-client
+
+Tiny Python client for [Nocturne](https://nocturne.runstratus.com) — the bioacoustic species classifier for insects, amphibians, and other non-bird wildlife from [Stratus Labs](https://huggingface.co/stratus-labs).
+
+## Install
+
+```bash
+pip install nocturne-client
+```
+
+## Use
+
+```python
+from nocturne_client import Nocturne
+
+n = Nocturne()
+r = n.predict("cicada.wav", top_k=5, threshold=0.15)
+for p in r.predictions:
+    print(f"{p.score:.3f}  {p.species}")
+```
+
+Batch:
+
+```python
+results = n.predict_batch(["clip1.wav", "clip2.wav", "clip3.wav"])
+```
+
+CLI:
+
+```bash
+nocturne-client predict clip.wav --top-k 5
+nocturne-client health
+nocturne-client vocab
+```
+
+## Environment
+
+- `NOCTURNE_URL` — override the default endpoint (`https://nocturne.runstratus.com`) if you're self-hosting.
+
+## Rate limits
+
+The public endpoint is capped at 10 requests per minute per IP. The client retries automatically on 429 with linear backoff. For batch work at scale, self-host the model (weights on HuggingFace at [`stratus-labs/nocturne-v1-teacher`](https://huggingface.co/stratus-labs/nocturne-v1-teacher)) or contact Stratus Labs.
+
+## License
+
+Apache-2.0. Model weights are CC-BY-4.0 (see the model card).

nocturne_client-1.0.0/README.md

@@ -0,0 +1,46 @@
+# nocturne-client
+
+Tiny Python client for [Nocturne](https://nocturne.runstratus.com) — the bioacoustic species classifier for insects, amphibians, and other non-bird wildlife from [Stratus Labs](https://huggingface.co/stratus-labs).
+
+## Install
+
+```bash
+pip install nocturne-client
+```
+
+## Use
+
+```python
+from nocturne_client import Nocturne
+
+n = Nocturne()
+r = n.predict("cicada.wav", top_k=5, threshold=0.15)
+for p in r.predictions:
+    print(f"{p.score:.3f}  {p.species}")
+```
+
+Batch:
+
+```python
+results = n.predict_batch(["clip1.wav", "clip2.wav", "clip3.wav"])
+```
+
+CLI:
+
+```bash
+nocturne-client predict clip.wav --top-k 5
+nocturne-client health
+nocturne-client vocab
+```
+
+## Environment
+
+- `NOCTURNE_URL` — override the default endpoint (`https://nocturne.runstratus.com`) if you're self-hosting.
+
+## Rate limits
+
+The public endpoint is capped at 10 requests per minute per IP. The client retries automatically on 429 with linear backoff. For batch work at scale, self-host the model (weights on HuggingFace at [`stratus-labs/nocturne-v1-teacher`](https://huggingface.co/stratus-labs/nocturne-v1-teacher)) or contact Stratus Labs.
+
+## License
+
+Apache-2.0. Model weights are CC-BY-4.0 (see the model card).

nocturne_client-1.0.0/nocturne_client/__init__.py

@@ -0,0 +1,169 @@
+"""Tiny Python client for the Nocturne v1 bioacoustic classifier API.
+
+    pip install nocturne-client
+    from nocturne_client import Nocturne
+    n = Nocturne()  # points at https://nocturne.runstratus.com by default
+    print(n.predict("clip.wav", top_k=5))
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+import requests
+
+__version__ = "1.0.0"
+DEFAULT_URL = os.environ.get("NOCTURNE_URL", "https://nocturne.runstratus.com")
+
+
+@dataclass
+class Prediction:
+    species: str
+    score: float
+
+
+@dataclass
+class PredictionResponse:
+    filename: str
+    duration_seconds: float
+    chunks_analyzed: int
+    inference_seconds: float
+    device: str
+    model: str
+    predictions: list[Prediction]
+
+    @classmethod
+    def from_json(cls, j: dict) -> "PredictionResponse":
+        return cls(
+            filename=j["filename"],
+            duration_seconds=j.get("duration_seconds", 0.0),
+            chunks_analyzed=j.get("chunks_analyzed", 0),
+            inference_seconds=j.get("inference_seconds", 0.0),
+            device=j.get("device", ""),
+            model=j.get("model", ""),
+            predictions=[Prediction(**p) for p in j.get("predictions", [])],
+        )
+
+
+class Nocturne:
+    """Client for the Nocturne bioacoustic species classifier."""
+
+    def __init__(self, base_url: str = DEFAULT_URL, timeout: float = 60.0,
+                 max_retries: int = 3, retry_delay: float = 5.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self._session = requests.Session()
+        self._session.headers.update({"User-Agent": f"nocturne-client/{__version__}"})
+
+    def health(self) -> dict:
+        r = self._session.get(f"{self.base_url}/health", timeout=10)
+        r.raise_for_status()
+        return r.json()
+
+    def vocab(self) -> list[str]:
+        r = self._session.get(f"{self.base_url}/vocab", timeout=30)
+        r.raise_for_status()
+        return r.json().get("species", [])
+
+    def predict(self, audio: str | Path | bytes, top_k: int = 5,
+                threshold: float = 0.15) -> PredictionResponse:
+        """Predict species for a single clip. Retries on 429 rate limits."""
+        params = {"top_k": top_k, "threshold": threshold}
+        for attempt in range(self.max_retries):
+            r = self._session.post(
+                f"{self.base_url}/predict", params=params,
+                files={"file": self._as_file(audio)}, timeout=self.timeout,
+            )
+            if r.status_code == 429:
+                if attempt < self.max_retries - 1:
+                    time.sleep(self.retry_delay * (attempt + 1))
+                    continue
+            r.raise_for_status()
+            return PredictionResponse.from_json(r.json())
+        raise RuntimeError(f"rate limited after {self.max_retries} retries")
+
+    def predict_batch(self, audios: Iterable[str | Path | bytes], top_k: int = 5,
+                      threshold: float = 0.15, chunk_size: int = 20) -> list[PredictionResponse]:
+        """Predict for a batch of clips. Batched to <=20/request per server cap."""
+        audios = list(audios)
+        results = []
+        for i in range(0, len(audios), chunk_size):
+            batch = audios[i : i + chunk_size]
+            files = [("files", self._as_file(a)) for a in batch]
+            r = self._session.post(
+                f"{self.base_url}/predict-batch",
+                params={"top_k": top_k, "threshold": threshold},
+                files=files, timeout=self.timeout * 3,
+            )
+            r.raise_for_status()
+            for item in r.json().get("results", []):
+                if "error" in item:
+                    print(f"[nocturne-client] {item['filename']}: {item['error']}")
+                    continue
+                results.append(PredictionResponse.from_json(item))
+        return results
+
+    def _as_file(self, audio):
+        if isinstance(audio, (str, Path)):
+            p = Path(audio)
+            return (p.name, open(p, "rb"), "application/octet-stream")
+        if isinstance(audio, (bytes, bytearray)):
+            return ("clip.wav", bytes(audio), "audio/wav")
+        raise TypeError(f"unsupported audio type: {type(audio)}")
+
+
+def _cli():
+    """Command-line: nocturne-client predict clip.wav [--top-k 5] [--threshold 0.15]"""
+    import argparse
+    ap = argparse.ArgumentParser(prog="nocturne-client")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_pred = sub.add_parser("predict", help="Predict for one or more audio files.")
+    p_pred.add_argument("files", nargs="+")
+    p_pred.add_argument("--top-k", type=int, default=5)
+    p_pred.add_argument("--threshold", type=float, default=0.15)
+    p_pred.add_argument("--json", action="store_true", help="Emit raw JSON per file.")
+
+    sub.add_parser("health")
+    sub.add_parser("vocab")
+
+    args = ap.parse_args()
+    n = Nocturne()
+
+    if args.cmd == "health":
+        print(json.dumps(n.health(), indent=2))
+        return
+    if args.cmd == "vocab":
+        v = n.vocab()
+        print(f"{len(v)} species:")
+        for s in v[:50]:
+            print(f"  {s}")
+        if len(v) > 50:
+            print(f"  ... ({len(v)-50} more)")
+        return
+    if args.cmd == "predict":
+        if len(args.files) == 1:
+            r = n.predict(args.files[0], top_k=args.top_k, threshold=args.threshold)
+            if args.json:
+                print(json.dumps(r.__dict__, default=lambda o: o.__dict__, indent=2))
+            else:
+                print(f"{r.filename} ({r.duration_seconds}s, {r.inference_seconds}s inference):")
+                for p in r.predictions:
+                    print(f"  {p.score:.3f}  {p.species}")
+        else:
+            results = n.predict_batch(args.files, top_k=args.top_k, threshold=args.threshold)
+            for r in results:
+                print(f"{r.filename}:")
+                for p in r.predictions[:5]:
+                    print(f"  {p.score:.3f}  {p.species}")
+                print()
+
+
+if __name__ == "__main__":
+    _cli()

nocturne_client-1.0.0/nocturne_client.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: nocturne-client
+Version: 1.0.0
+Summary: Python client for the Nocturne bioacoustic species classifier (by Stratus Labs).
+Author: Stratus Labs
+License: Apache-2.0
+Project-URL: Homepage, https://nocturne.runstratus.com
+Project-URL: Model, https://huggingface.co/stratus-labs/nocturne-v1-teacher
+Project-URL: Source, https://github.com/stratus-labs/nocturne-client
+Keywords: bioacoustics,audio,classification,insects,amphibians,ecology
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# nocturne-client
+
+Tiny Python client for [Nocturne](https://nocturne.runstratus.com) — the bioacoustic species classifier for insects, amphibians, and other non-bird wildlife from [Stratus Labs](https://huggingface.co/stratus-labs).
+
+## Install
+
+```bash
+pip install nocturne-client
+```
+
+## Use
+
+```python
+from nocturne_client import Nocturne
+
+n = Nocturne()
+r = n.predict("cicada.wav", top_k=5, threshold=0.15)
+for p in r.predictions:
+    print(f"{p.score:.3f}  {p.species}")
+```
+
+Batch:
+
+```python
+results = n.predict_batch(["clip1.wav", "clip2.wav", "clip3.wav"])
+```
+
+CLI:
+
+```bash
+nocturne-client predict clip.wav --top-k 5
+nocturne-client health
+nocturne-client vocab
+```
+
+## Environment
+
+- `NOCTURNE_URL` — override the default endpoint (`https://nocturne.runstratus.com`) if you're self-hosting.
+
+## Rate limits
+
+The public endpoint is capped at 10 requests per minute per IP. The client retries automatically on 429 with linear backoff. For batch work at scale, self-host the model (weights on HuggingFace at [`stratus-labs/nocturne-v1-teacher`](https://huggingface.co/stratus-labs/nocturne-v1-teacher)) or contact Stratus Labs.
+
+## License
+
+Apache-2.0. Model weights are CC-BY-4.0 (see the model card).

nocturne_client-1.0.0/nocturne_client.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+nocturne_client/__init__.py
+nocturne_client.egg-info/PKG-INFO
+nocturne_client.egg-info/SOURCES.txt
+nocturne_client.egg-info/dependency_links.txt
+nocturne_client.egg-info/entry_points.txt
+nocturne_client.egg-info/requires.txt
+nocturne_client.egg-info/top_level.txt

nocturne_client-1.0.0/nocturne_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nocturne_client-1.0.0/nocturne_client.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nocturne-client = nocturne_client:_cli

nocturne_client-1.0.0/nocturne_client.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

nocturne_client-1.0.0/nocturne_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+nocturne_client

nocturne_client-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nocturne-client"
+version = "1.0.0"
+description = "Python client for the Nocturne bioacoustic species classifier (by Stratus Labs)."
+readme = "README.md"
+license = {text = "Apache-2.0"}
+authors = [{name = "Stratus Labs"}]
+requires-python = ">=3.9"
+dependencies = ["requests>=2.28"]
+keywords = ["bioacoustics", "audio", "classification", "insects", "amphibians", "ecology"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: Apache Software License",
+  "Topic :: Multimedia :: Sound/Audio :: Analysis",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+[project.urls]
+Homepage = "https://nocturne.runstratus.com"
+Model = "https://huggingface.co/stratus-labs/nocturne-v1-teacher"
+Source = "https://github.com/stratus-labs/nocturne-client"
+
+[project.scripts]
+nocturne-client = "nocturne_client:_cli"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nocturne_client*"]

nocturne_client-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+