How felixbur/nkululeko works
Project Type and Purpose
• This is not a web app but a CLI-driven, modular machine-learning experiment framework in Python. It orchestrates the flow from raw audio datasets (CSV, WAV) through feature extraction, model training/optimization, evaluation, and report generation. Users control everything via INI-style configuration files, and the library provides pluggable components for data loading, feature extractors, models, augmenters, optimizers, and reporting.
High-Level File Structure Analysis
• nkululeko/: core library and CLI entry-points
• nkululeko/nkululeko.py, ensemble.py, multidb.py, etc. – top-level commands
• runmanager.py, experiment.py, modelrunner.py, optimizationrunner.py – orchestration engines
• data/, feat_extract/, augmenting/, models/, reporting/, segmenting/ – plugin bins
• flags.py, glob_conf.py – configuration & factory logic
• data/: raw dataset definitions and processing scripts (one subfolder per corpus)
• examples/ & meta/: sample INI files and demo scripts
• scripts/: convenience scripts to launch pipelines
Main Components & Their Relationships
• python -m nkululeko.nkululeko, ensemble, multidb, demo, explore, augment, predict, segment, resample, optim, flags
↳ parse --config exp.ini and hand off to RunManager
• Modules: flags.py, glob_conf.py, nkuluflag.py
↳ read INI, resolve sections ([DATA], [FEATS], [MODEL], etc.), create factory objects
• Classes: RunManager, Experiment, ModelRunner, OptimizationRunner
↳ orchestrate pipeline steps
• nkululeko/data/dataset.py, dataset_csv.py, plus project-specific data/.../process_database.py
↳ read CSVs, apply splitting strategies, return in-memory datasets
• nkululeko/feat_extract/feats_*.py, transformer_feature_extractor.py
↳ wrappers around Praat, opensmile, wav2vec2, CLAP, etc.
• augmenting/, resample.py
↳ random splicing, synthetic sampling (SMOTE), resampling rates
• nkululeko/models/model_*.py (SVM, XGB, KNN, MLP, CNN, GMM, etc.)
↳ scikit-learn & torch/tensorflow wrappers
h. Optimization
• optim.py, OptimizationRunner
↳ grid search, hyperparameter sweeps
• reporting/report.py, latex_writer.py, plots.py
↳ confusion matrix, t-SNE, feature importance, PDF/LaTeX reports
j. Utilities & Core
• constants.py, cacheddataset.py, file_checker.py, logging, stats, file I/O
Architectural Patterns & Design Principles
• Plugin/Flexible Factory: all extractors, models, metrics are loaded by name from config.
• Pipeline Separation: clear stages (Data → Features → [Augment] → Model → Report).
• Config-Driven: no hard-coded parameters; the INI drives the flow.
• Modular & Testable: each plugin has its own tests under nkululeko/*/tests and tests/.
• CLI Frontend / Core Engine: entry-points delegate to the same core pipeline.