ai-pam-pipeline v1.0.0

First public release of ai-pam-pipeline, an open-source Python toolkit for reproducible convolutional neural network (CNN)-based vocalization detection and classification in Passive Acoustic Monitoring (PAM) applications. The framework implements a formally defined six-stage pipeline — spanning audio acquisition, label parsing and windowing, spectrogram generation, image preprocessing, k-fold cross-validation training, and in-domain and cross-domain evaluation — whose entire parameter space is specified through a two-level YAML configuration system.

What's included

A six-stage YAML-driven pipeline covering the full workflow from raw audio and Audacity label files to trained CNN models and cross-domain evaluation reports:

• Stage 1 — seek-based audio I/O with optional resampling and normalization (lib/ai_pam_audio.py)
• Stage 2 — label parsing, timeline discretization, exclusion-zone filtering, RLE segmentation, and window generation with optional scroll augmentation (lib/ai_pam_parse.py, lib/ai_pam_segment.py)
• Stage 3 — STFT-based spectrogram rendering to PIL images (lib/ai_pam_spectro.py)
• Stage 4 — optional OpenCV image preprocessing pipeline: CLAHE, morphological operators, edge detectors, polarity inversion (lib/ai_pam_filters.py)
• Stage 5 — stratified k-fold cross-validation CNN training with warm-up, early stopping, and per-fold model export (ai_pam_train.py)
• Stage 6 — in-domain evaluation and cross-domain testing against external datasets (ai_pam_crosstest.py)

Configuration is managed through a two-level YAML system: conf/master_config.yaml defines all defaults and serves as the schema; a project YAML overrides only the parameters that differ. The run configuration is saved alongside every output artifact, guaranteeing full reproducibility.

Features

• Per-class include/exclude label rules with overlap exclusion zones
• center_short_events for consistent spatial positioning of short vocalizations
• Scroll augmentation configurable globally or per class via augmentation_scroll
• Keras version compatibility shim for legacy .h5 models (_load_model_compat)
• Plug-in CNN architecture: any build_model(input_shape, n_classes, kernel_size) callable works with ai_pam_train.py
• Unified report generation via lib/ai_pam_report.py

License

Released under the [Apache License 2.0] (see LICENSE).