Metadata-Version: 2.4
Name: augelab-ai
Version: 1.1.10
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: pillow ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: s3-pypi-manager==1.2.0 ; extra == 'dev'
Requires-Dist: s3-pypi-manager==1.2.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_AUGE_CUDNN_CONVOLUTION=disabled|enabled` (native Auge only; disabled by default)

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

Native Auge convolution uses its deterministic CUDA kernels by default. Set
`AUGELAB_AI_AUGE_CUDNN_CONVOLUTION=enabled` only for controlled compatibility
or performance investigation; it is not a wheel packaging option and never
bundles CUDA libraries.

## 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.

### Auge array inference

Native German Auge models accept contiguous or strided HWC `numpy.uint8`
images without file encoding or decoding. The facade makes a contiguous view
only when required and keeps it alive while Rust releases the GIL for
preprocessing and inference.

```python
from augelab_ai import (
    AugeDevice,
    AugeInferenceOptions,
    AugeInputColorOrder,
    AugeWinzig,
)

model = AugeWinzig.from_checkpoint("model.auge")
detections = model.predict_array(
    image,
    options=AugeInferenceOptions(
        device=AugeDevice.CUDA,
        input_color_order=AugeInputColorOrder.BGR,
    ),
)
```

Array inference requires an HWC three-channel `uint8` image. Use `RGB` for
Pillow-style arrays and `BGR` for OpenCV and AugeLab Studio images.

### Auge training progress

Native German Auge models can emit real loss snapshots after every training image,
at completed optimizer-batch boundaries, or at completed-epoch boundaries. The
mode is enum-only and has no effect on the training trajectory or resume
compatibility.

```python
from augelab_ai import AugeDevice, AugeProgressMode, AugeTrainingOptions, AugeWinzig

model = AugeWinzig(class_names=["part"])
result = model.train(
    "dataset",
    "training-output",
options=AugeTrainingOptions(
        device=AugeDevice.CUDA,
        progress_mode=AugeProgressMode.IMAGE,
    ),
    progress_callback=lambda progress: print(
        progress.batch,
        progress.batches,
        progress.batch_loss,
        progress.train_loss,
    ),
)
```

### Multi-GPU training

Native Auge and Fast/Accurate classification training accept explicit CUDA
ordinals through `cuda_device_ids=(0, 1, ...)`. The effective batch is global:
each optimizer step partitions it across replicas, reduces gradients
synchronously in stable rank order, then applies one optimizer/EMA update and
broadcasts the parameters. Learning rates are therefore unchanged from
single-GPU training.

```python
options = AugeTrainingOptions(
    device=AugeDevice.CUDA,
    cuda_device_ids=(0, 1),
    target_effective_batch_size=16,
)
```

All selected GPUs must be visible and have the same CUDA compute capability,
and the effective batch must contain at least one image per replica. Exact
resume requires the same replica count but may remap ordinals. PaDiM, legacy
`AugeMatch`, and CPU YOLO training remain single-device.

`progress_callback` is required whenever `progress_mode` is enabled. `IMAGE`
events are emitted after every image objective and use `batch_loss` for that
image's objective. `BATCH` events occur only after an optimizer batch is applied
and use `batch_loss` for the completed-batch mean. `train_loss` is always the
running mean for the current epoch.

For interactive development, launch the repository-owned training dashboard:

```powershell
tools\auge_training_dashboard\launch-dashboard.ps1
```

It provides live batch loss and ETA charts, runtime and hardware diagnostics,
resumable sessions, checkpoint inspection, and folder inference. Generated
artifacts remain under the ignored `target\auge-training-gui` directory. See
[the dashboard guide](tools/auge_training_dashboard/README.md) for configuration
and validation commands.

FP32 CUDA training defaults to `activation_recomputation=AugeToggle.DISABLED`:
it keeps the exact FP32 backbone and decoder activations on the device so
reverse execution does not replay forward prefixes. Set it to
`AugeToggle.ENABLED` only when a lower VRAM footprint is more important than
training throughput. Mixed FP16 keeps recomputation enabled automatically
until it has a matching binary16 activation cache.

### Auge pretrained backbones

Each German Auge detector variant has a separate native pretrained backbone.
The weights are immutable, hash-addressed S3 artifacts and are not bundled in
the Python wheel. Their HTTPS URL, SHA-256, and byte count are exposed by the
installed `augelab_ai` package:

| Variant | Constant prefix |
| --- | --- |
| `AugeWinzig` | `PRETRAINED_AUGE_WINZIG_*` |
| `AugeKlein` | `PRETRAINED_AUGE_KLEIN_*` |
| `Auge` | `PRETRAINED_AUGE_*` |
| `AugeGross` | `PRETRAINED_AUGE_GROSS_*` |
| `AugeRiesig` | `PRETRAINED_AUGE_RIESIG_*` |
| `AugeGigant` | `PRETRAINED_AUGE_GIGANT_*` |

Replace `*` with `URL`, `SHA256`, or `BYTES`. Downloaders must verify both the
declared byte count and SHA-256 before moving a temporary download into the
persistent model directory. Initialize training with the matching artifact:

```python
from augelab_ai import AugeFineTuneMode, AugeTrainingOptions, AugeWinzig

model = AugeWinzig(
    class_names=["part"],
    pretrained_backbone_path="auge-winzig.abackbone",
)
model.train(
    "dataset",
    "training-output",
    options=AugeTrainingOptions(
        fine_tune_mode=AugeFineTuneMode.FROZEN_BACKBONE,
    ),
)
```

The artifact initializes the transformer backbone. `FULL` fine-tuning updates
it; `FROZEN_BACKBONE` keeps every backbone parameter and its optimizer/EMA state
unchanged, stops backpropagation before the backbone, and omits CUDA backbone
reverse workspaces while training the projector and detection network. Detection
heads remain Auge-owned and are initialized for the supplied customer classes.
An artifact is architecture-specific; loading it into a different Auge variant
is rejected.

Official YOLOv4-CSP pretrained convolutional weights are a verified external
asset and are not bundled in the wheel. Studio downloaders use the public
`PRETRAINED_YOLOV4_CSP_URL`, `PRETRAINED_YOLOV4_CSP_SHA256`, and
`PRETRAINED_YOLOV4_CSP_BYTES` constants, resume partial HTTP transfers, and
atomically promote the file only after byte-count and SHA-256 verification.

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.

YOLO inference and checkpoint evaluation default to bounded post-processing:
CPU uses classwise hard NMS after a confidence-sorted top-K, while CUDA uses one
batched hard-NMS mask kernel followed by deterministic top-K selection. The
defaults are `pre_nms_topk=3000` and `max_detections=300`. Pass
`DetectorPostprocessOptions(nms_mode=DetectorNmsMode.LEGACY)` to retain the
uncapped calculation. YOLO worker manifests expose the same training-window
controls as `evaluation_postprocess_mode`, `evaluation_pre_nms_topk`, and
`evaluation_max_detections`; evaluation events report the resolved values.

CUDA YOLO training supports explicit single- and multi-GPU execution. `[net]
batch` remains the global optimizer batch and the learning rate is unchanged:
each device accumulates its partition on-device, gradients are reduced in
selected-device order, rank 0 applies one SGD update, and the parameters are
broadcast before the next batch.

```python
from augelab_ai import (
    YoloGradientTransport,
    YoloMicroBatchPolicy,
    YoloTrainingAlgorithm,
    YoloTrainingDevice,
    darknet,
)

summary = darknet.train_yolo(
    data="dataset.data",
    config="model.cfg",
    weights="model.weights",
    output="training-run",
    device=YoloTrainingDevice.CUDA,
    cuda_device_ids=(0, 1),
    gradient_transport=YoloGradientTransport.AUTO,
    micro_batch_policy=YoloMicroBatchPolicy.AUTO,
    training_algorithm=YoloTrainingAlgorithm.DYNAMIC_INTERP_IOU,
    iterations=100,
)
print(summary.per_device_micro_batch, summary.images_per_second)
```

`YoloTrainingAlgorithm.LEGACY` remains the default and preserves the original
native loss, constant learning rate, and plain-SGD update. The opt-in
`DYNAMIC_INTERP_IOU` mode uses Dynamic InterpIoU box regression, global
Darknet-style anchor matching, configured YOLO normalizers and ignore
thresholds, `[net]` burn-in/step scheduling, momentum, and weight decay. Its
reported loss includes background objectness BCE and is therefore not
numerically comparable to the legacy loss. Compare validation mAP from
identical starting weights when choosing between the modes.
Dynamic InterpIoU currently requires fixed network dimensions because rebuilding
CUDA buffers for random multiscale training would discard optimizer momentum.

CUDA training executes true batched forward/backward tensors. Positive
`subdivisions` retain fixed Darknet-compatible geometry; `subdivisions=0` is
the convenient alias for `YoloMicroBatchPolicy.AUTO`. AUTO benchmarks feasible
capacities before the first optimizer update, selects the best measured
global-step throughput, and writes `yolo-microbatch-autotune.json` beside the
output weights. Compatible resumed runs verify and reuse that capacity. AUTO
is CUDA-only, and zero is never written into the prepared cfg.

`AUTO` uses CUDA peer transfers only when every selected device can access every
other selected device; otherwise it uses pinned host staging. Use
`PEER_TO_PEER` to require a fully connected topology or `HOST_STAGED` to force
the portable path. Device IDs must be unique and visible, all selected devices
must have the same compute capability, and the global batch must be at least
the replica count. Empty `cuda_device_ids` retains CUDA device 0.

The training CLI exposes the same controls:

```powershell
py -3.12 scripts\train_yolo_darknet.py ... --device cuda --training-algorithm dynamic_interp_iou
```

Set `AUGELAB_AI_YOLO_PROFILE=1` for synchronized CUDA phase timings. This
improves timing attribution but adds synchronization overhead, so use the
default summary for normal throughput measurements.

For repeatable throughput comparisons with the `augelab-darknet` package used
by AugeLab Studio, use the non-gating benchmark harness:

```powershell
py -3.12 scripts\benchmark_yolo_training.py --config model.cfg --weights model.weights --data dataset.data --iterations 100 --global-batch 8 --fixed-micro-batch 4 --cuda-devices 0 --trainer both --output target\yolo-training-benchmark
```

The harness performs an unmeasured warm-up, writes raw JSON and logs below the
output directory, and reports median/p95 iteration time and images per second.
It discovers Studio's packaged Darknet executable without modifying the Studio
checkout. Add `--profile` only when synchronized `augelab-ai` phase timings are
needed.

Smart Training uses validation mAP50 for stage extension, plateau detection, and
best-checkpoint selection. Loss does not drive healthy run-length decisions. A
separate conservative divergence guard can still stop a run when sustained
catastrophic loss indicates unsafe optimization, even if periodic mAP is still
rising. See [YOLO Smart Training behavior](docs/yolo-smart-training.md) for the
decision rules, default thresholds, worker events, and injected-curve tests.

## 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.

## Native Classification and PaDiM

The package also provides native EfficientViT-L1 Fast, EVA-02-B/14 Accurate, and
compact MobileNetV4 Conv Small classification, plus native PaDiM anomaly-detection
paths and a ResNet18 compatibility algorithm. MobileNetV4 classification is a
supported single-GPU tier; its PaDiM channel path remains experimental. These models
support direct NumPy-array CPU/CUDA inference without JPEG encode/decode or PyTorch
in the runtime wheel.

Approved pretrained backbone URLs, SHA-256 digests, and byte counts are exposed as
Rust-owned `PRETRAINED_*` constants from the installed `augelab_ai` package. The
weights remain separate, immutable S3 artifacts and are never bundled in a wheel.
`augelab-ai` does not download or cache them; applications such as AugeLab Studio
own transfer, verification, cache policy, and passing the resulting local path to
the training API.

See [the classification and PaDiM guide](docs/classification-and-padim.md) for model
artifacts, training and inference examples, MVTec AD evaluation, benchmarks,
deployment constraints, and current acceptance scope.

## AutoLearn: PromptSeg and Visual Prototype

The package now includes two native AutoLearn framework modules:

- EfficientViT-SAM-L0-compatible promptable segmentation with points, boxes,
  iterative mask prompts, automatic masks, and mask-head fine-tuning.
- Open-set Visual Prototype matching over the existing EfficientViT-L1, EVA-02-B/14,
  MobileNetV4 Conv Small, and ResNet18 compatibility backbones.

Both modules expose explicit CPU and CUDA device selection. PromptSeg CUDA currently
uses the native CUDA EfficientViT encoder with the SAM neck, decoder, and trainable
mask heads on deterministic FP32 CPU execution; runtime metadata identifies that
hybrid boundary. Visual Prototype uses each existing classifier's native CPU/CUDA
feature path directly.

See [the AutoLearn implementation guide](docs/autolearn.md) for checkpoint conversion,
APIs, training scope, open-set calibration, and correctness gates.

### 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% |

