Metadata-Version: 2.4
Name: augelab-ai
Version: 1.1.6
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.9.79 ; (platform_machine == 'AMD64' and sys_platform == 'win32' and extra == 'cuda12') or (platform_machine == 'aarch64' and sys_platform == 'linux' and extra == 'cuda12') or (platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda12')
Requires-Dist: nvidia-cuda-nvrtc-cu12==12.9.86 ; (platform_machine == 'AMD64' and sys_platform == 'win32' and extra == 'cuda12') or (platform_machine == 'aarch64' and sys_platform == 'linux' and extra == 'cuda12') or (platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda12')
Requires-Dist: nvidia-cublas-cu12==12.9.2.10 ; (platform_machine == 'AMD64' and sys_platform == 'win32' and extra == 'cuda12') or (platform_machine == 'aarch64' and sys_platform == 'linux' and extra == 'cuda12') or (platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda12')
Requires-Dist: nvidia-cudnn-cu12==9.7.1.26 ; (platform_machine == 'AMD64' and sys_platform == 'win32' and extra == 'cuda12') or (platform_machine == 'aarch64' and sys_platform == 'linux' and extra == 'cuda12') or (platform_machine == 'x86_64' and sys_platform == 'linux' and 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==1.1.0 ; extra == 'dev'
Requires-Dist: s3-pypi-manager==1.1.0 ; extra == 'publish'
Provides-Extra: cuda12
Provides-Extra: dev
Provides-Extra: publish
License-File: LICENSE.txt
Summary: AugeLab YOLOv4 native 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 package-owned
CUDA and CPU inference engines.

The default Python runtime dependency is only `numpy`. The native extension loads
the NVIDIA CUDA driver from the host driver installation, and loads CUDA
user-mode libraries from the installed NVIDIA Python packages by default. On
Jetson Linux/aarch64 systems detected by `/etc/nv_tegra_release`, it uses only
the system JetPack CUDA stack because that stack is tied to the installed OS
release.
Inference and CPU training do not depend on Darknet, TensorRT, ONNX Runtime, or
OpenCV.

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 on Windows x64 and Linux x86_64/aarch64. They pin CUDA 12.9 and cuDNN
9.7.1.26. The target machine still needs a compatible NVIDIA driver.

JetPack users must install the base package, not `[cuda12]`, and use the CUDA,
NVRTC, cuBLAS, and cuDNN libraries supplied by their JetPack OS image:

```bash
pip install augelab-ai
```

## Runtime Environment

- `AUGELAB_AI_CUDA_ARCH=native|all|all-major|compute_XX|sm_XX|XX`
- `AUGELAB_AI_CUDA_PROVIDER=auto|system|python-wheels`
- `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_PROVIDER=auto` resolves to `system` on Jetson and
`python-wheels` elsewhere. On Jetson, `python-wheels` is rejected: JetPack
devices must use only their OS-provided CUDA/cuDNN stack. Set
`AUGELAB_AI_CUDA_PATH`, `CUDA_PATH`, or `CUDA_HOME` for a nonstandard JetPack
system location; `AUGELAB_AI_NVIDIA_CUDA_ROOTS` cannot point at package roots.
On other platforms, `python-wheels` selects `[cuda12]` libraries and `system`
selects system roots first. `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.
CUDA remains the default device, and callers can explicitly select CPU.

```python
from augelab_ai import (
    DetectorDevice,
    DetectorEngine,
    DetectorPreprocessMode,
    darknet as detect,
)

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

The Python facade accepts enum options only. YOLO inference in this package is
native and returns detection data only; callers such as Studio own
visualization. Use `device=DetectorDevice.CPU` for CPU inference. Unsupported cfg
features, unavailable CUDA when CUDA is requested, and native runtime failures
raise explicit exceptions instead of silently changing devices.
Use `augelab_ai.cuda_available()` or `augelab_ai.darknet.cuda_available()` for a
cheap CUDA driver/device availability probe before constructing a detector.

CPU YOLO training is exposed through the same package facade and uses the native
Rust training path without adding Darknet binaries to the wheel:

```python
from augelab_ai import YoloTrainingDevice, YoloTrainingPreflight, darknet

summary = darknet.train_yolo(
    data="dataset.data",
    config="model.cfg",
    weights="model.weights",
    output="training-run",
    device=YoloTrainingDevice.CPU,
    iterations=1,
    batch=64,
    subdivisions=64,
    preflight=YoloTrainingPreflight.CONFIG,
)
```

Use `darknet.prepare_yolo_training_run(...)` to materialize the rewritten cfg,
data file, image lists, and ASCII-safe dataset view without running training.
Training preparation validates the rewritten cfg by default. Use
`YoloTrainingPreflight.CONFIG_AND_WEIGHTS` when the starting weights should also
be checked against the native loader, and `YoloTrainingPreflight.DISABLED` only
when Studio has already validated the generated cfg elsewhere.

## 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, Darknet, or OpenCV 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/cuDNN harness: non-JetPack `[cuda12]` installs use CUDA 12.9 user-mode
  packages and cuDNN 9.7.1.26. CUDA 12.9 retains offline support for Maxwell
  and Pascal-class hardware that CUDA 13 removed.
- JetPack exception: JetPack remains OS-provided and system-only. Its shipped
  cuDNN 8.9 compatibility is retained and is not replaced by the `[cuda12]`
  dependency line.
- 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: runtime NVRTC supports native Maxwell through
  Blackwell CC 12.0 (`50;52;53;60;61;62;70;72;75;80;86;87;89;90;100;120`) and
  experimental forward targets `101;103;121`. The legacy `110` selector is
  reserved for the JetPack system provider. 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 or draw detections.

```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.1.2`
- 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% |

