Metadata-Version: 2.4
Name: augelab-ai
Version: 1.0.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Dist: numpy>=1.23,<2.3
Requires-Dist: nvidia-cuda-runtime-cu12>=12.6,<13 ; extra == 'cuda12'
Requires-Dist: nvidia-cuda-nvrtc-cu12>=12.6,<13 ; extra == 'cuda12'
Requires-Dist: nvidia-cublas-cu12>=12.6,<13 ; extra == 'cuda12'
Requires-Dist: nvidia-cudnn-cu12>=9.3,<10 ; extra == 'cuda12'
Requires-Dist: maturin>=1.8,<2.0 ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: s3-pypi-manager ; extra == 'dev'
Requires-Dist: s3-pypi-manager ; extra == 'publish'
Provides-Extra: cuda12
Provides-Extra: dev
Provides-Extra: publish
Summary: AugeLab YOLOv4 CUDA inference package
Author-email: AugeLab Tech <info@augelab.com>
License: Proprietary
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# AugeLab AI

Rust/PyO3 Python package for YOLOv4-family object detection with a package-owned
CUDA inference engine.

The default Python runtime dependency is only `numpy`. The native extension loads
the NVIDIA CUDA driver, NVRTC, cuBLAS, and cuDNN from the installed CUDA toolkit
at runtime when available. It does not depend on Darknet, TensorRT, ONNX Runtime,
OpenCV, or bundled NVIDIA runtime libraries.

Customers can install CUDA/cuDNN user-space libraries from PyPI with:

```bash
pip install augelab-ai[cuda12]
```

These extras install the CUDA runtime, NVRTC, cuBLAS, and cuDNN Python NVIDIA
packages. The target machine still needs an NVIDIA driver or JetPack driver
stack.

## Runtime Environment

- `AUGELAB_AI_CUDA_PATH=<CUDA toolkit root>`
- `CUDA_PATH=<CUDA toolkit root>`
- `AUGELAB_AI_CUDA_ARCH=native|all|all-major|compute_XX|sm_XX|XX`
- `AUGELAB_AI_CONV_BACKEND=auto|cudnn|cublas|hybrid|tiled|naive`
- `AUGELAB_AI_CUDNN_WORKSPACE_MB=<megabytes>`
- `AUGELAB_AI_CUDNN_MATH=default|tensor|allow_conversion`
- `AUGELAB_AI_CUDNN_ALGO=auto|implicit_gemm|implicit_precomp_gemm|gemm|direct|fft|fft_tiling|winograd|winograd_nonfused`

`AUGELAB_AI_CUDA_PATH` takes precedence over automatic discovery. On Windows, the
loader also probes installed CUDA toolkit directories under `C:\Program
Files\NVIDIA GPU Computing Toolkit\CUDA` newest-first, then falls back to
`CUDA_PATH`. `auto` prefers cuDNN convolution when available, with cuBLAS and
custom CUDA kernels as fallbacks. cuDNN maxpool is used opportunistically.
CUDA kernels are compiled with NVRTC at runtime for the detected GPU by default.
Use `AUGELAB_AI_CUDA_ARCH` only when you need to force a specific PTX target.

## API Shape

`augelab_ai.darknet.Detector` is kept as the compatibility facade for Studio, but
it is backed by the custom CUDA YOLO engine.

```python
from augelab_ai import DetectorDevice, DetectorEngine, darknet as detect

detector = detect.Detector(
    weight="model.weights",
    config="model.cfg",
    classes="model.names",
    engine=DetectorEngine.NATIVE,
    device=DetectorDevice.CUDA,
)
```

The Python facade accepts enum options only. YOLO inference in this package is
native CUDA only; unsupported cfg features, unavailable CUDA, and native runtime
failures raise explicit exceptions instead of falling back to CPU.
Use `augelab_ai.cuda_available()` or `augelab_ai.darknet.cuda_available()` for a
cheap CUDA driver/device availability probe before constructing a detector.

## Build

```powershell
py -V:Astral/CPython3.12.8 -m pip install maturin
py -V:Astral/CPython3.12.8 -m maturin build --release --out dist\wheelhouse
py -V:Astral/CPython3.12.8 scripts/validate_wheel.py dist\wheelhouse\augelab_ai-*.whl
```

The wheel must not bundle CUDA, cuDNN, cuBLAS, or Darknet binaries.

Release builds produce three wheels:

```powershell
py -3.12 scripts\build_release_wheels.py
```

See [docs/building.md](docs/building.md) for the Windows x86_64, Linux x86_64
glibc 2.31, and Linux arm64 glibc 2.31 build flow.
See [docs/gpu-compatibility.md](docs/gpu-compatibility.md) for the supported
NVIDIA GPU generations and compute capability mapping.

### Build Constraints

- CUDA baseline: build and test against the lowest practical CUDA 12.x toolkit,
  ideally CUDA 12.0, so the wheels remain compatible with newer CUDA 12.x
  installations. CUDA 11 is not a target.
- cuDNN baseline: cuDNN 9.x is preferred. cuDNN 8.9 is best-effort for JetPack
  6.0 systems that ship CUDA 12.2 and cuDNN 8.9.
- Python baseline: CPython 3.12. ABI-stable wheels target `cp312-abi3` so one
  wheel can cover newer compatible Python versions.
- Release wheels: Windows x86_64, Linux `manylinux_2_31_x86_64`, and Linux
  `manylinux_2_31_aarch64`.
- Linux ABI floor: glibc 2.31.
- CUDA architecture target: broad CUDA 12-era coverage through runtime NVRTC
  native compilation. Recognized explicit SM values span `50` through `121`
  for Maxwell, Pascal, Volta, Turing, Ampere, Ada, Hopper, Blackwell, and
  Jetson Nano/Xavier/Orin/T-series targets. Pre-Maxwell GPUs are not targeted.

## OpenCV-DNN Benchmark

OpenCV is used only by the benchmark script as a comparison baseline. The
`augelab-ai` runtime does not import OpenCV.

```powershell
python scripts\benchmark_opencv_dnn.py --opencv-target cuda --warmup 3 --rounds 20
```

By default the script uses Studio's YOLOv4 cfg/classes, the
`augelab_extra_modules` weights, and five Studio sample images. Pass
`--config`, `--weights`, `--classes`, and `--images` to benchmark a custom model
or image set.

### Reference Result

This package exists because the native CUDA path can outperform Studio's
OpenCV-DNN CUDA path while keeping the Darknet-compatible facade and adding
broader cfg/layer compatibility. OpenCV remains useful as a benchmark baseline.

Local reference benchmark from July 3, 2026:

- GPU: NVIDIA GeForce GTX 1660 Ti
- Driver/CUDA reported by `nvidia-smi`: 572.61 / CUDA 12.8
- Package: `augelab-ai 1.0.0`
- OpenCV: Studio OpenCV-DNN payload, `cv2 4.12.0-dev`
- Model/data: Studio YOLOv4 cfg, `yolov4.pw`, COCO classes, five Studio sample
  images
- Command: `python scripts\benchmark_opencv_dnn.py --opencv-target cuda --warmup 3 --rounds 20`
- Timed work per run: 5 images x 20 rounds = 100 inferences per backend
- Detection counts matched on every run:
  `indoor=14`, `street=9`, `crosswalk=24`, `cyclists=20`, `ppe=3`

| Run | OpenCV-DNN CUDA | `augelab-ai` CUDA | Speedup | Latency reduction |
| --- | ---: | ---: | ---: | ---: |
| 1 | 116.882 ms/image, 8.56 FPS | 89.585 ms/image, 11.16 FPS | 1.305x | 23.4% |
| 2 | 123.033 ms/image, 8.13 FPS | 106.627 ms/image, 9.38 FPS | 1.154x | 13.3% |
| 3 | 119.351 ms/image, 8.38 FPS | 95.720 ms/image, 10.45 FPS | 1.247x | 19.8% |
| Mean | 119.755 ms/image, 8.35 FPS | 97.311 ms/image, 10.33 FPS | 1.231x | 18.7% |

