Metadata-Version: 2.4
Name: nocturne-client
Version: 1.1.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).
