Metadata-Version: 2.4
Name: ospreyai
Version: 0.1.0
Summary: Dynamic multi-stream video-analytics library on NVIDIA DeepStream 8.0
Author: ILKAY-BRAHIM
License: Apache-2.0
Project-URL: Homepage, https://ospreyai.dev
Keywords: deepstream,video-analytics,rtsp,yolo,tensorrt,gstreamer
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: opencv-python
Provides-Extra: server
Requires-Dist: fastapi; extra == "server"
Requires-Dist: uvicorn[standard]; extra == "server"
Requires-Dist: pydantic>=2; extra == "server"
Requires-Dist: pydantic-settings; extra == "server"
Requires-Dist: python-multipart; extra == "server"

# Osprey

Dynamic, multi-stream video-analytics library built on **NVIDIA DeepStream 8.0**
— installable with `pip`, run **bare-metal, no Docker**.

```python
from osprey.client import DeepStreamClient, FrameData

class VehicleCounter(DeepStreamClient):
    def _process_frame(self, frame: FrameData):
        for obj in frame.objects:
            self._draw_object(frame.surface, obj)   # box + tracking label

VehicleCounter().start()   # serves RTSP for every discovered stream
```

---

## What Osprey installs for you

Osprey is a Python layer on top of the DeepStream SDK. The GStreamer plugins
(`nvstreammux`, `nvinfer`, `nvtracker`, `nvunixfdsink/src`, `nvdsosd`, …) and the
`pyds` bindings are **not** on PyPI. Rather than make you set that up by hand,
Osprey ships an **end-to-end bootstrap** that reproduces, bare-metal, what the
DeepStream container image build does — so a fresh Ubuntu 24.04 box becomes a
working Osprey host with no Docker.

Target platform (DeepStream 8.0, x86/dGPU):

| Component | Version |
|---|---|
| OS | Ubuntu 24.04 |
| NVIDIA driver | R570.133.20 |
| CUDA | 12.8 |
| TensorRT | 10.9.0.34 |
| cuDNN | 9.7.1 |
| GStreamer | 1.24.2 |

---

## Quick start (end-to-end)

```bash
# 1. Install the Python package (pure-Python + precompiled parser .so)
pip install "osprey[server]"

# 2. Bootstrap the DeepStream stack bare-metal (needs root; ~one-time)
sudo osprey-bootstrap

# 3. Run
osprey-server     # FastAPI control plane on :8000  (POST /api/v1/add …)
osprey-client     # discovers sockets, serves RTSP per stream
```

`osprey-bootstrap` runs five stages (each also runnable on its own; see below).
If the NVIDIA driver is (re)installed in stage 10, **reboot** before running the
pipeline.

### Bootstrap stages

| Stage | Does | Mirrors |
|---|---|---|
| `00_system_deps` | apt build toolchain + GStreamer runtime | image apt layer |
| `10_cuda_trt_cudnn` | driver R570 + CUDA 12.8 + cuDNN 9.7 + TensorRT 10.9 | base image |
| `20_deepstream_sdk` | DeepStream 8.0 SDK `.deb` from NGC → GStreamer plugins | base image |
| `30_pyds` | build + install `pyds` for your Python | image bindings build |
| `40_native_libs` | verify shipped parsers/serializer; TRT-plugin patch is **manual** | image compile step |

Useful toggles (read by the scripts, pass straight through):

```bash
sudo OSPREY_ASSUME_CUDA=1 osprey-bootstrap    # already have driver/CUDA/TRT/cuDNN
sudo OSPREY_ONLY=30 osprey-bootstrap          # run a single stage (e.g. just pyds)
sudo OSPREY_DS_VERSION=8.0 osprey-bootstrap   # override DeepStream version
```

> **Security note.** Osprey does **not** auto-download or overwrite your system
> TensorRT library. Some ONNX models embed end-to-end NMS (`EfficientNMS_TRT`)
> and need a patched `libnvinfer_plugin`; because that means replacing a system
> library with an external binary, Osprey leaves it as a deliberate manual step
> (see the reference `patch_libnvinfer.sh`). Standard YOLO/RT-DETR detection and
> segmentation need no patch.

---

## Already have DeepStream 8.0?

Skip the bootstrap and just use the library:

```bash
pip install "osprey[server]"
python3 -c "from osprey.client import DeepStreamClient; print('ok')"
```

The bundled native libraries (`osprey/**/lib/*.so`) are compiled for
DeepStream 8.0 / CUDA 12.8 and match the platform table above.

---

## CLIs

| Command | Purpose |
|---|---|
| `osprey-bootstrap` | Bare-metal end-to-end DeepStream install (root) |
| `osprey-server` | FastAPI control plane — add/remove streams at runtime |
| `osprey-client` | Discover sockets, run app logic, serve RTSP |
| `osprey-build-engines` | Pre-build TensorRT engines from `GIE_N_CONFIG` |

---

## Testing

To exercise the library in a GPU DeepStream container (install → REST add →
GPU inference → RTSP output), see [`docs/TESTING.md`](docs/TESTING.md). It's the
exact runbook used to validate Osprey end-to-end.
