Metadata-Version: 2.4
Name: nullpunkt
Version: 1.0.0
Summary: Nullpunkt behavioral anomaly detection API client
Author-email: Nohvel <api@nohvel.com>
License: Proprietary
Project-URL: Homepage, https://nohvel.com/nullpunkt
Project-URL: Documentation, https://nohvel.com/docs
Project-URL: API Portal, https://api.nohvel.com/portal
Keywords: anomaly-detection,behavioral-analysis,computer-vision,security,surveillance,machine-learning,api-client
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# Nullpunkt

Python client for the [Nullpunkt](https://nohvel.com/nullpunkt) behavioral anomaly detection API by [Nohvel](https://nohvel.com).

## Install

```bash
pip install nullpunkt
```

## Quickstart

```python
from nullpunkt import NullpunktClient

client = NullpunktClient(api_key='npk_...')

# Fit baseline from normal-behavior data
client.fit_baseline('normal_scene.mp4', wait=True)

# Run detection
result = client.detect('scene_to_analyze.mp4', wait=True)

print(f"Anomaly rate: {result.anomaly_rate:.1%}")
print(f"Anomalous frames: {result.anomaly_frames} / {result.total_frames}")

for event in result.events:
    print(f"  Frame {event.frame}: score={event.score:.3f}, agents={event.agents}")
```

## Authentication

Pass your API key directly or set the `NULLPUNKT_API_KEY` environment variable:

```bash
export NULLPUNKT_API_KEY=npk_...
```

```python
client = NullpunktClient()  # reads from environment
```

Get an API key at [api.nohvel.com/portal](https://api.nohvel.com/portal).

## Supported Input Formats

- Video files: `.mp4`, `.avi`, `.mkv`
- Pre-tracked CSV: `frame, track_id, cx, cy, w, h`
- Pre-tracked JSON: `{"frames": [{"frame_id": 0, "detections": [...]}]}`

## Async Jobs

By default, `fit_baseline()` and `detect()` block until the job completes.
For non-blocking usage, pass `wait=False` and poll manually:

```python
job_id = client.detect('scene.mp4', wait=False)

while True:
    status = client.get_job_status(job_id)
    if status['status'] == 'complete':
        break
    time.sleep(10)

result = client.get_results(job_id)
```

## Documentation

Full API reference: [nohvel.com/docs](https://nohvel.com/docs)

## Support

[api@nohvel.com](mailto:api@nohvel.com)
