audio-anomaly-detection

A modular FastAPI service for audio anomaly/classification inference with dynamic model selection.

What This Service Does

• Accepts an audio file and runs model inference.
• Supports multiple models selected by:
  • query param model_name
  • fallback DEFAULT_MODEL_NAME from env
• Returns:
  • prediction
  • probability
  • all_probabilities
  • latency_ms

API Endpoints

• GET /
  • Health/root message.
• GET /models
  • Lists available model names and the default model.
• POST /predict-anomaly
  • Main inference endpoint.
  • Multipart file field: file
  • Optional query: model_name

Project Structure

audio-anomaly-detection/
├── main.py
├── requirements.txt
├── .env.example
├── config/
│   └── models.json
├── app/
│   ├── main.py
│   ├── config.py
│   ├── dependencies.py
│   ├── schemas.py
│   ├── api/
│   │   └── routes.py
│   └── services/
│       ├── errors.py
│       ├── inference_service.py
│       ├── registry.py
│       └── pipeline.py
├── features/
│   └── feature_extractor.py
├── models/
│   └── *.joblib
├── tests/
│   ├── test_registry.py
│   └── test_api_routes.py
└── test_api.py

Setup

1. Use Python 3.10+.
2. Install dependencies:

pip install -r requirements.txt

3. Configure environment:

cp .env.example .env

Configuration

Preferred model config approach

Use a readable JSON file:

• .env
  • MODELS_CONFIG_PATH=config/models.json
• config/models.json
  • model definitions keyed by model name

Env variables

• API_TITLE
• API_VERSION
• SAMPLE_RATE
• DEFAULT_MODEL_NAME
• MODELS_CONFIG_PATH (preferred)
• MODELS_CONFIG_JSON (fallback inline JSON)

Legacy single-model env vars are also supported if both MODELS_CONFIG_PATH and MODELS_CONFIG_JSON are missing.

Run

Option 1:

python main.py

Option 2:

uvicorn app.main:app --reload

Swagger docs:

• http://127.0.0.1:8000/docs

Quick API Usage

List available models:

curl http://127.0.0.1:8000/models

Predict with default model:

curl -X POST "http://127.0.0.1:8000/predict-anomaly" \
  -F "file=@/path/to/sample.wav"

Predict with specific model:

curl -X POST "http://127.0.0.1:8000/predict-anomaly?model_name=ultimate_v7" \
  -F "file=@/path/to/sample.wav"

Add New Model (models.json workflow)

1. Open config/models.json.
2. Copy an existing model block and add a new model key.
3. Update artifact paths (model_path, scaler_path, optional label/drop files).
4. Keep:
   • feature_extractor: "default"
   • predictor: "sklearn_proba" unless you also implement new strategy code.
5. Ensure DEFAULT_MODEL_NAME exists in config/models.json.

Example:

{
  "ultimate_v7": {
    "model_path": "models/ultimate_v7_model.joblib",
    "scaler_path": "models/scaler.joblib",
    "label_encoder_path": "models/label_encoder.joblib",
    "dropped_features_path": "models/dropped_features.joblib",
    "feature_extractor": "default",
    "predictor": "sklearn_proba"
  },
  "ultimate_v8": {
    "model_path": "models/ultimate_v8_model.joblib",
    "scaler_path": "models/ultimate_v8_scaler.joblib",
    "label_encoder_path": "models/ultimate_v8_label_encoder.joblib",
    "dropped_features_path": "models/ultimate_v8_dropped_features.joblib",
    "feature_extractor": "default",
    "predictor": "sklearn_proba"
  }
}

Verify:

curl http://127.0.0.1:8000/models
curl -X POST "http://127.0.0.1:8000/predict-anomaly?model_name=ultimate_v8" -F "file=@/path/sample.wav"

Tests

Run test suite:

python -m pytest -q

If python is not available in shell:

python3 -m pytest -q

CLI utility:

python test_api.py "/path/to/your/audio.wav"

Worker Docs

• Worker high-level design: docs/SQS_WORKER_HLD.md
• Worker implementation guide: docs/AUDIO_ANOMALY_PIPELINE_IMPLEMENTATION.md
• Worker runtime entrypoint: python -m app.workers.sqs_anomaly_worker

Notes

• features/feature_extractor.py is actively used by the runtime pipeline.
• utils/model_handler.py is legacy and not part of the current inference path.
• Detailed technical design is documented in REFACTOR_EXPLANATION.md.