Initial commit: Added application code

.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+.pytest_cache/
+.coverage
+
+# Env
+.env
+
+# Virtual environments
+.venv/
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Model cache (let HF download fresh)
+.cache/
+models/.cache/
+
+# Development files
+.pytest_cache/
+notebooks/
+tests/
+docs/

Dockerfile

@@ -0,0 +1,50 @@
+# Use CUDA base for GPU support
+FROM nvidia/cuda:13.0.1-runtime-ubuntu22.04
+
+# Set timezone non-interactively
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=UTC
+
+# Install Python and basic dependencies
+RUN apt-get update && apt-get install -y \
+    software-properties-common \
+    && add-apt-repository ppa:deadsnakes/ppa \
+    && apt-get update && apt-get install -y \
+    python3.11 \
+    python3.11-dev \
+    python3.11-venv \
+    python3.11-distutils \
+    git \
+    libsndfile1 \
+    ffmpeg \
+    curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && ln -sf /usr/bin/python3.11 /usr/bin/python3 \
+    && ln -sf /usr/bin/python3.11 /usr/bin/python \
+    && curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11
+
+WORKDIR /app
+
+# Copy and install Python dependencies
+COPY pyproject.toml poetry.lock* ./
+RUN python3.11 -m pip install poetry && \
+    poetry config virtualenvs.create false && \
+    poetry install --only=main
+
+# Copy application code
+COPY src/ ./src/
+COPY app/ ./app/
+COPY config/ ./config/
+COPY models/ ./models/
+COPY scripts/ ./scripts/
+COPY .env ./
+
+# Set environment
+ENV PYTHONPATH="/app"
+ENV HF_HOME="/app/.cache/huggingface"
+
+# Hugging Face Spaces specific, expose port 7860
+EXPOSE 7860
+
+# Run on port 7860 for HF Spaces
+CMD ["uvicorn", "app.server:app", "--host", "0.0.0.0", "--port", "7860"]

app/schemas.py

@@ -0,0 +1,47 @@
+from pydantic import BaseModel
+from typing import Dict, List, Optional
+
+
+# Pydantic model for the base response
+class BaseResponse(BaseModel):
+    status: str
+    message: Optional[str] = None
+
+
+class WelcomeResponse(BaseResponse):
+    endpoints: Dict[str, str]
+
+
+class ModelInfoResponse(BaseResponse):
+    model_name: str
+    model_version: str
+    supported_formats: List[str]
+    max_file_size_mb: int
+    training_info: Optional[Dict] = None
+    last_updated: Optional[str] = None
+
+
+# Pydantic model for the prediction response
+class PredictionResponse(BaseModel):
+    status: str
+    lyrics: str
+    audio_file_name: str
+    audio_content_type: str
+    audio_file_size: int
+    results: Optional[Dict] = None
+
+
+class PredictionXAIResponse(BaseModel):
+    status: str
+    lyrics: str
+    audio_file_name: str
+    audio_content_type: str
+    audio_file_size: int
+    results: Optional[Dict] = None
+
+
+# Pydantic model for the error response
+class ErrorResponse(BaseModel):
+    status: str = "error"
+    code: int
+    message: str

app/server.py

@@ -0,0 +1,202 @@
+# Fast API imports
+from fastapi import Depends, FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+
+# Processing imports
+import librosa
+import io
+
+# Utils/schemas imports
+from app.schemas import (
+    ErrorResponse,
+    ModelInfoResponse,
+    PredictionResponse,
+    PredictionXAIResponse,
+    WelcomeResponse,
+)
+from app.utils import load_config
+
+# Model/XAI-related imports
+from scripts.explain import musiclime
+from scripts.predict import predict_pipeline
+
+
+# Load config at startup
+config = load_config()
+
+# Extract configuration values
+MAX_FILE_SIZE = config["file_upload"]["max_file_size_mb"] * 1024 * 1024
+MAX_LYRICS_LENGTH = config["file_upload"]["max_lyrics_length"]
+ALLOWED_AUDIO_TYPES = config["file_upload"]["allowed_audio_types"]
+
+# Initialize fast API app with extracted config values
+app = FastAPI(title=config["server"]["title"], version=config["server"]["version"])
+
+# Initialize CORS with config values
+cors_config = config["api"]["cors"]
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=cors_config["allow_origins"],
+    allow_credentials=cors_config["allow_credentials"],
+    allow_methods=cors_config["allow_methods"],
+    allow_headers=cors_config["allow_headers"],
+)
+
+
+async def validate_audio_file(audio_file: UploadFile = File(...)):
+    """Validate audio file type and size."""
+    # Check file size
+    audio_content = await audio_file.read()
+    if len(audio_content) > MAX_FILE_SIZE:
+        raise HTTPException(
+            status_code=400,
+            detail=f"File too large. Maximum size is {MAX_FILE_SIZE // (1024*1024)}MB.",
+        )
+
+    # Check file type
+    if audio_file.content_type not in ALLOWED_AUDIO_TYPES:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid file type. Supported formats: {', '.join(ALLOWED_AUDIO_TYPES)}",
+        )
+
+    # Reset file pointer for later use
+    audio_file.file.seek(0)
+    return audio_file, audio_content
+
+
+def validate_lyrics(lyrics: str = Form(...)):
+    """Validate lyrics length and content."""
+    if len(lyrics) > MAX_LYRICS_LENGTH:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Lyrics too long. Maximum length is {MAX_LYRICS_LENGTH} characters.",
+        )
+
+    # Basic sanitization, remove excessive whitespace
+    lyrics = lyrics.strip()
+    if not lyrics:
+        raise HTTPException(
+            status_code=400,
+            detail="Lyrics cannot be empty.",
+        )
+
+    return lyrics
+
+
+@app.get("/", response_model=WelcomeResponse, tags=["Root"])
+def root():
+    """
+    Root endpoint to check if the API is running.
+    """
+    return WelcomeResponse(
+        status="success",
+        message="Welcome to Bach or Bot API!",
+        endpoints={
+            "/": "This welcome message",
+            "/docs": "FastAPI auto-generated API docs",
+            "/api/v1/model/info": "Model information and capabilities",
+            "/api/v1/predict": "POST endpoint for bach-or-bot prediction",
+            "/api/v1/explain": "POST endpoint for prediction with explainability",
+        },
+    )
+
+
+@app.post(
+    "/api/v1/predict",
+    response_model=PredictionResponse,
+    responses={400: {"model": ErrorResponse}, 500: {"model": ErrorResponse}},
+)
+async def predict_music(
+    lyrics: str = Depends(validate_lyrics), audio_file_data=Depends(validate_audio_file)
+):
+    """
+    Endpoint to predict whether a music sample is human-composed or AI-generated.
+    """
+    try:
+        # Get the audio file and content from sanitized and cleaned audio file
+        audio_file, audio_content = audio_file_data
+
+        # Load audio from uploaded file with error handling for corrupted files
+        try:
+            audio_data, sr = librosa.load(io.BytesIO(audio_content))
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=f"Invalid audio file: {str(e)}")
+
+        # Call MLP predict runner script to get results
+        results = predict_pipeline(audio_data, lyrics)
+
+        return PredictionResponse(
+            status="success",
+            lyrics=lyrics,
+            audio_file_name=audio_file.filename,
+            audio_content_type=audio_file.content_type,
+            audio_file_size=len(audio_content),
+            results=results,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post(
+    "/api/v1/explain",
+    response_model=PredictionXAIResponse,
+    responses={400: {"model": ErrorResponse}, 500: {"model": ErrorResponse}},
+)
+async def predict_music_with_xai(
+    lyrics: str = Depends(validate_lyrics), audio_file_data=Depends(validate_audio_file)
+):
+    """
+    Endpoint to predict whether a music sample is human-composed or AI-generated with explainability.
+    """
+    try:
+        # Get the audio file and content from sanitized and cleaned audio file
+        audio_file, audio_content = audio_file_data
+
+        # Load audio from uploaded file with error handling for corrupted files
+        try:
+            audio_data, sr = librosa.load(io.BytesIO(audio_content))
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=f"Invalid audio file: {str(e)}")
+
+        # Call musiclime runner script to get results
+        results = musiclime(audio_data, lyrics)
+
+        return PredictionXAIResponse(
+            status="success",
+            lyrics=lyrics,
+            audio_file_name=audio_file.filename,
+            audio_content_type=audio_file.content_type,
+            audio_file_size=len(audio_content),
+            results=results,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/v1/model/info", response_model=ModelInfoResponse, tags=["Model"])
+async def get_model_info():
+    """
+    Get information about the current model and its capabilities.
+    """
+    try:
+        # Get supported formats from config
+        supported_formats = [fmt.replace("audio/", "") for fmt in ALLOWED_AUDIO_TYPES]
+
+        return ModelInfoResponse(
+            status="success",
+            message="Model information retrieved successfully",
+            model_name="Bach or Bot",
+            model_version="1.0.0",  # TODO: Load from model metadata when available
+            supported_formats=supported_formats,
+            max_file_size_mb=config["file_upload"]["max_file_size_mb"],
+            training_info={
+                "dataset": "Human-Composed and AI-generated music samples",
+                "architecture": "To be specified",  # TODO: Update when model is implemented
+                "accuracy": "To be determined",  # TODO: Update with actual metrics
+            },
+            last_updated="2024-01-01T00:00:00Z",  # TODO: Update with actual timestamp
+        )
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

app/utils.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+import yaml
+
+
+def load_config():
+    """
+    Load server configs from YAML file.
+    """
+    # Define path first
+    config_path = Path(__file__).parent.parent / "config" / "server_config.yml"
+
+    if not config_path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {config_path}")
+
+    with open(config_path, "r") as file:
+        return yaml.safe_load(file)

config/data_config.yml

@@ -0,0 +1,8 @@
+base_dir: "."
+
+paths:
+  dataset_npz: "data/processed/training_data.npz"
+  dataset_csv: "data/external/songs_dataset.csv"
+  raw_dir: "data/raw"
+  processed_dir: "data/processed"
+  pca_path: "data/processed/pca_model.pkl"

config/model_config.yml

@@ -0,0 +1,11 @@
+mlp:
+  hidden_layers: [1024, 512, 256, 128, 64, 32] # 6 hidden layers
+  dropout: [0.4, 0.3, 0.5, 0.5, 0.5] # Dropout rates for each layer
+  learning_rate: 0.0001 # Adam optimizer
+  batch_size: 128 # Number of samples processed together
+  epochs: 200 # Maximum training iterations
+  patience: 5 # Early stopping patience
+
+  weight_decay: 0.1 # L2 regularization
+  gradient_clipping: 0.5 # Prevent exploding gradients
+  mixup_alpha: 0.2 # For data augmentation during trainign, 0 disables MixUp

config/server_config.yml

@@ -0,0 +1,25 @@
+# Server Configuration
+server:
+  title: "Bach or Bot API"
+  version: "1.0.0"
+
+# File upload limits and validation
+file_upload:
+  # Maximum file size in MB
+  max_file_size_mb: 10
+  # Maximum characters for lyrics
+  max_lyrics_length: 10000
+  allowed_audio_types:
+    - "audio/wav"
+    - "audio/mpeg"
+    - "audio/mp3"
+    - "application/octet-stream"
+
+# API Configuration
+api:
+  cors:
+    # TODO: Change to specific origins in production
+    allow_origins: ["*"]
+    allow_credentials: true
+    allow_methods: ["*"]
+    allow_headers: ["*"]

pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "bach-or-bot"
+version = "0.1.0"
+description = "A binary classifier to distinguish between Human-composed and AI-generated music"
+authors = [
+    {name = "Acelle Krislette Rosales",email = "acellekrislette@gmail.com"},
+    {name = "Hans Christian Queja",email = "hansqueja8@gmail.com"},
+    {name = "Regina Bonfiacio",email = "bonifacioregina06@gmail.com"},
+    {name = "Sean Matthew Sinalubong",email = "s3amatth3wsinalubong@gmail.com"},
+    {name = "Syruz Ken Domingo",email = "syruzkenc.domingo@gmail.com"},
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "librosa (>=0.11.0,<0.12.0)",
+    "pandas (>=2.3.2,<3.0.0)",
+    "soundfile (>=0.13.1,<0.14.0)",
+    "torchaudio (>=2.8.0,<3.0.0)",
+    "transformers (==4.44.2)",
+    "llm2vec (>=0.2.3,<0.3.0)",
+    "peft (>=0.17.1,<0.18.0)",
+    "timm (>=1.0.19,<2.0.0)",
+    "pyyaml (>=6.0.2,<7.0.0)",
+    "tqdm (>=4.67.1,<5.0.0)",
+    "torch (>=2.8.0,<3.0.0)",
+    "openunmix (>=1.3.0,<2.0.0)",
+    "fastapi (>=0.117.1,<0.118.0)",
+    "uvicorn (>=0.36.0,<0.37.0)",
+    "scikit-learn (>=1.5.2)",
+    "torchao (>=0.13.0,<0.14.0)",
+    "lime (>=0.2.0.1,<0.3.0.0)",
+    "hf-xet (>=1.1.10,<2.0.0)",
+    "huggingface-hub[cli] (>=0.35.3,<0.36.0)",
+    "pytest (>=8.4.2,<9.0.0)",
+    "python-multipart (>=0.0.20,<0.0.21)",
+    "python-dotenv (>=1.1.1,<2.0.0)"
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry]
+package-mode = false

scripts/evaluate.py

@@ -0,0 +1,164 @@
+"""
+MLP Model Evaluation Script for AI vs Human Music Detection
+==========================================================
+
+This script evaluates the performance of the trained MLP classifier on test data.
+It gives a complete performance report showing how well the model can distinguish
+between AI-generated and human-composed music.
+
+What this script does:
+- Loads our saved/trained MLP model
+- Tests it on held-out test data (music the model has never seen)
+- Calculates accuracy, precision, recall, and F1-score
+- Reports confusion statistics (true positives, true negatives, false positives, false negatives)
+- Displays sample predictions with probabilities for transparency
+
+Quick Start:
+---------------------------
+# Basic evaluation with default model path
+python evaluate.py
+
+# Evaluate a specific model
+python evaluate.py --model "models/fusion/mlp_multimodal.pth"
+
+# From code
+from evaluate import evaluate_model
+results = evaluate_model("models/fusion/mlp_multimodal.pth")
+
+Performance Metrics Explained:
+------------------------------
+- Accuracy: Overall correctness (how many songs classified correctly)
+- Precision: Of songs predicted as human, how many actually were human
+- Recall: Of all human songs, how many did we correctly identify  
+- F1-Score: Balance between precision and recall (harmonic mean)
+- Confusion stats: 
+    TP = Human songs correctly identified  
+    TN = AI songs correctly identified  
+    FP = AI songs incorrectly labeled as human  
+    FN = Human songs incorrectly labeled as AI  
+
+Expected Output:
+----------------
+Loading model from: models/fusion/mlp_multimodal.pth
+Loaded dataset: (50000, 684), Labels: 50000
+Test set size: (10000, 684)
+Evaluating model on test set...
+
+Sample predictions:
+True: 1, Pred: 1, Prob: 0.8234  # Correctly identified human song
+True: 0, Pred: 0, Prob: 0.1456  # Correctly identified AI song
+True: 1, Pred: 0, Prob: 0.4123  # Missed a human song (false negative)
+
+=== Evaluation Results ===
+Test Accuracy: 87.54%
+Test Loss: 0.3412
+Precision: 0.8832
+Recall: 0.8654
+F1-Score: 0.8742
+"""
+
+import argparse
+import logging
+import numpy as np
+from pathlib import Path
+
+from src.models.mlp import build_mlp, load_config
+from src.utils.config_loader import DATASET_NPZ
+from sklearn.model_selection import train_test_split
+
+# Set up logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+
+def evaluate_model(model_path: str = "models/fusion/mlp_multimodal.pth"):
+    logger.info(f"Loading model from: {model_path}")
+    
+    # Check if dataset exists
+    if not Path(DATASET_NPZ).exists():
+        raise FileNotFoundError(f"Dataset not found at {DATASET_NPZ}. Run train.py first.")
+    
+    # Load the full dataset
+    loaded_data = np.load(DATASET_NPZ)
+    X = loaded_data["X"]
+    Y = loaded_data["Y"]
+    
+    logger.info(f"Loaded dataset: {X.shape}, Labels: {len(Y)}")
+    
+    # Split data (same as training)
+    from src.utils.dataset import dataset_scaler
+    data = dataset_scaler(X, Y)
+    X_test, y_test = data["test"]
+    
+    logger.info(f"Test set size: {X_test.shape}")
+    
+    # Load configuration
+    config = load_config("config/model_config.yml")
+    
+    # Build model architecture (needed for loading weights)
+    mlp_classifier = build_mlp(input_dim=X_test.shape[1], config=config)
+    
+    # Load trained model
+    mlp_classifier.load_model(model_path)
+    
+    # Evaluate on test set
+    logger.info("Evaluating model on test set...")
+    test_results = mlp_classifier.evaluate(X_test, y_test)
+    
+    # Get predictions for detailed analysis
+    probabilities, predictions = mlp_classifier.predict(X_test)
+
+    # Show a few sample predictions
+    for i in range(10): 
+        print(f"True: {y_test[i]}, Pred: {predictions[i]}, Prob: {probabilities[i]:.4f} "
+              f"(Probability of predicted class)")
+    
+    logger.info("=== Evaluation Results ===")
+    logger.info(f"Test Accuracy: {test_results['test_accuracy']:.2f}%")
+    logger.info(f"Test Loss: {test_results['test_loss']:.4f}")
+    
+    # Additional statistics
+    true_positives = np.sum((y_test == 1) & (predictions == 1))
+    true_negatives = np.sum((y_test == 0) & (predictions == 0))
+    false_positives = np.sum((y_test == 0) & (predictions == 1))
+    false_negatives = np.sum((y_test == 1) & (predictions == 0))
+    
+    precision = true_positives / (true_positives + false_positives) if (true_positives + false_positives) > 0 else 0
+    recall = true_positives / (true_positives + false_negatives) if (true_positives + false_negatives) > 0 else 0
+    f1_score = 2 * (precision * recall) / (precision + recall) if (precision + recall) > 0 else 0
+    
+    logger.info(f"Precision: {precision:.4f}")
+    logger.info(f"Recall: {recall:.4f}")
+    logger.info(f"F1-Score: {f1_score:.4f}")
+    
+    # Include all metrics in return dict
+    return {
+        "test_accuracy": test_results["test_accuracy"],
+        "test_loss": test_results["test_loss"],
+        "precision": precision,
+        "recall": recall,
+        "f1_score": f1_score,
+        "true_positives": int(true_positives),
+        "true_negatives": int(true_negatives),
+        "false_positives": int(false_positives),
+        "false_negatives": int(false_negatives)
+    }
+
+
+def main():
+    """Main evaluation function."""
+    parser = argparse.ArgumentParser(description='Evaluate Bach-or-Bot MLP classifier')
+    parser.add_argument('--model', default='models/fusion/mlp_multimodal.pth',
+                       help='Path to trained model')
+    args = parser.parse_args()
+    
+    try:
+        results = evaluate_model(args.model)
+        logger.info("Evaluation completed successfully!")
+    except Exception as e:
+        logger.error(f"Evaluation failed: {str(e)}")
+        raise
+
+
+if __name__ == "__main__":
+    main()

scripts/explain.py

@@ -0,0 +1,74 @@
+import numpy as np
+from datetime import datetime
+from src.musiclime.explainer import MusicLIMEExplainer
+from src.musiclime.wrapper import MusicLIMEPredictor
+
+
+def musiclime(audio_data, lyrics_text):
+    """
+    MusicLIME wrapper for API usage.
+
+    Args:
+        audio_data: Audio array (from librosa.load or similar)
+        lyrics_text: String containing lyrics
+
+    Returns:
+        dict: Structured explanation results
+    """
+    start_time = datetime.now()
+
+    # Create musiclime instances
+    explainer = MusicLIMEExplainer()
+    predictor = MusicLIMEPredictor()
+
+    # Generate explanations
+    explanation = explainer.explain_instance(
+        audio=audio_data,
+        lyrics=lyrics_text,
+        predict_fn=predictor,
+        num_samples=1000,
+        labels=(1,),
+    )
+
+    # Get prediction info
+    original_prediction = explanation.predictions[0]
+    predicted_class = np.argmax(original_prediction)
+    confidence = float(np.max(original_prediction))
+
+    # Get top 10 features
+    top_features = explanation.get_explanation(label=1, num_features=10)
+
+    # Calculate runtime
+    end_time = datetime.now()
+    runtime_seconds = (end_time - start_time).total_seconds()
+
+    return {
+        "prediction": {
+            "class": int(predicted_class),
+            "class_name": "Human-Composed" if predicted_class == 1 else "AI-Generated",
+            "confidence": confidence,
+            "probabilities": original_prediction.tolist(),
+        },
+        "explanations": [
+            {
+                "rank": i + 1,
+                "modality": item["type"],
+                "feature_text": item["feature"],
+                "weight": float(item["weight"]),
+                "importance": abs(float(item["weight"])),
+            }
+            for i, item in enumerate(top_features)
+        ],
+        "summary": {
+            "total_features_analyzed": len(top_features),
+            "audio_features_count": len(
+                [f for f in top_features if f["type"] == "audio"]
+            ),
+            "lyrics_features_count": len(
+                [f for f in top_features if f["type"] == "lyrics"]
+            ),
+            "runtime_seconds": runtime_seconds,
+            "samples_generated": 1000,
+            "timestamp": start_time.isoformat(),
+        },
+    }

scripts/explain_test.py

@@ -0,0 +1,75 @@
+from datetime import datetime
+import librosa
+import numpy as np
+
+from pathlib import Path
+from src.musiclime.explainer import MusicLIMEExplainer
+from src.musiclime.wrapper import MusicLIMEPredictor
+from src.musiclime.print_utils import green_bold
+
+
+def explain():
+    # Start timing and time stamp to record how long the entire explanation thingy is
+    start_time = datetime.now()
+    print(
+        green_bold(
+            f"[MusicLIME] Started at: {start_time.strftime('%Y-%m-%d %H:%M:%S')}"
+        )
+    )
+
+    # Create musiclime-related instances
+    explainer = MusicLIMEExplainer()
+    predictor = MusicLIMEPredictor()
+
+    # Set the path for audio and lyrics [these are samples only - song is Silver Spring]
+    audio_path = Path("data/external/sample_2.mp3")
+    lyrics_path = Path("data/external/sample_2.txt")
+
+    # Load the audio as an object + load the lyrics as string
+    y, sr = librosa.load(audio_path)
+    lyrics_text = lyrics_path.read_text(encoding="utf-8")
+
+    # Generate explanations using musiclime
+    explanation = explainer.explain_instance(
+        audio=y,
+        lyrics=lyrics_text,
+        predict_fn=predictor,
+        num_samples=1000,
+        labels=(1,),
+    )
+
+    # Get original prediction (first sample is always the orig meaning unperturbed)
+    original_prediction = explanation.predictions[0]
+    predicted_class = np.argmax(original_prediction)
+
+    # Print explanations
+    results = explanation.get_explanation(label=1, num_features=10)
+    print("\n" + "=" * 80)
+    print(
+        f"[MusicLIME] Top 10 most important features for {"Human-Composed" if predicted_class == 1 else "AI-Generated"} prediction"
+    )
+    print("=" * 80)
+
+    for i, item in enumerate(results, 1):
+        print(
+            f"#{i:2d} | {item['type']:6s} | {item['feature'][:50]:50s} | weight: {item['weight']:+.6f}"
+        )
+
+    print("=" * 80)
+    print(f"[MusicLIME] Total features analyzed: {len(results)}")
+    print("[MusicLIME] Higher absolute weights = more important for the prediction")
+
+    # End timing and timestamp
+    end_time = datetime.now()
+    total_duration = end_time - start_time
+    total_minutes = total_duration.total_seconds() / 60
+    print(f"\n[MusicLIME] Finished at: {end_time.strftime('%Y-%m-%d %H:%M:%S')}")
+    print(
+        green_bold(
+            f"[MusicLIME] Total execution time: {total_minutes:.2f} minutes ({total_duration.total_seconds():.1f} seconds)"
+        )
+    )
+
+
+if __name__ == "__main__":
+    explain()

scripts/explain_with_json.py

@@ -0,0 +1,97 @@
+from datetime import datetime
+import librosa
+import numpy as np
+
+from pathlib import Path
+from src.musiclime.explainer import MusicLIMEExplainer
+from src.musiclime.wrapper import MusicLIMEPredictor
+from src.musiclime.print_utils import green_bold
+
+
+def explain():
+    # Start timing and time stamp to record how long the entire explanation thingy is
+    start_time = datetime.now()
+    print(
+        green_bold(
+            f"[MusicLIME] Started at: {start_time.strftime('%Y-%m-%d %H:%M:%S')}"
+        )
+    )
+
+    # Create musiclime-related instances
+    explainer = MusicLIMEExplainer()
+    predictor = MusicLIMEPredictor()
+
+    # Set the path for audio and lyrics [these are samples only - song is Silver Spring]
+    audio_path = Path("data/external/sample_2.mp3")
+    lyrics_path = Path("data/external/sample_2.txt")
+
+    # Load the audio as an object + load the lyrics as string
+    y, sr = librosa.load(audio_path)
+    lyrics_text = lyrics_path.read_text(encoding="utf-8")
+
+    # Generate explanations using musiclime
+    explanation = explainer.explain_instance(
+        audio=y,
+        lyrics=lyrics_text,
+        predict_fn=predictor,
+        num_samples=1000,
+        labels=(1,),
+    )
+
+    # Get original prediction (first sample is always the orig meaning unperturbed)
+    original_prediction = explanation.predictions[0]
+    predicted_class = np.argmax(original_prediction)
+    confidence = original_prediction[predicted_class]
+
+    # Create song info from the prediction
+    song_info = {
+        "filename": "sample.mp3",
+        "duration": f"{len(y)/44100:.1f}s",
+        "original_prediction": {
+            "class": "Human-Composed" if predicted_class == 1 else "AI-Generated",
+            "confidence": float(confidence),
+            "raw_probabilities": {
+                "AI": float(original_prediction[0]),
+                "Human": float(original_prediction[1]),
+            },
+        },
+    }
+
+    # Save with prediction data
+    explanation.save_to_json(
+        filepath=f"musiclime_explanation_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json",
+        song_info=song_info,
+        num_features=10,
+    )
+
+    # Print explanations
+    results = explanation.get_explanation(label=1, num_features=10)
+    print("\n" + "=" * 80)
+    print(
+        f"[MusicLIME] Top 10 most important features for {"Human-Composed" if predicted_class == 1 else "AI-Generated"} prediction"
+    )
+    print("=" * 80)
+
+    for i, item in enumerate(results, 1):
+        print(
+            f"#{i:2d} | {item['type']:6s} | {item['feature'][:50]:50s} | weight: {item['weight']:+.6f}"
+        )
+
+    print("=" * 80)
+    print(f"[MusicLIME] Total features analyzed: {len(results)}")
+    print("[MusicLIME] Higher absolute weights = more important for the prediction")
+
+    # End timing and timestamp
+    end_time = datetime.now()
+    total_duration = end_time - start_time
+    total_minutes = total_duration.total_seconds() / 60
+    print(f"\n[MusicLIME] Finished at: {end_time.strftime('%Y-%m-%d %H:%M:%S')}")
+    print(
+        green_bold(
+            f"[MusicLIME] Total execution time: {total_minutes:.2f} minutes ({total_duration.total_seconds():.1f} seconds)"
+        )
+    )
+
+
+if __name__ == "__main__":
+    explain()

scripts/predict.py

@@ -0,0 +1,82 @@
+from src.preprocessing.preprocessor import single_preprocessing
+from src.spectttra.spectttra_trainer import spectttra_predict
+from src.llm2vectrain.model import load_llm2vec_model
+from src.llm2vectrain.llm2vec_trainer import l2vec_single_train, load_pca_model
+from src.models.mlp import build_mlp, load_config
+from pathlib import Path
+from src.utils.config_loader import DATASET_NPZ
+from src.utils.dataset import instance_scaler
+
+from pathlib import Path
+import numpy as np
+import torch
+
+
+def predict_pipeline(audio, lyrics: str):
+    """
+    Predict script which includes preprocessing, feature extraction, and
+    training the MLP model for a single data sample.
+
+    Parameters
+    ----------
+    audio : audio_object
+        Audio object file
+
+    lyric : string
+        Lyric string
+
+    Returns
+    -------
+    prediction : str
+        A string result of the prediction
+
+    label : int
+        A numerical representation of the prediction
+    """
+
+    # Instantiate X and Y vectors
+    X, Y = None, None
+
+    # Instantiate LLM2Vec Model
+    llm2vec_model = load_llm2vec_model()
+
+    # Preprocess both audio and lyrics
+    audio, lyrics = single_preprocessing(audio, lyrics)
+
+    # Call the train method for both models
+    audio_features = spectttra_predict(audio)
+    lyrics_features = l2vec_single_train(llm2vec_model, lyrics)
+
+    # Reduce the lyrics using saved PCA model
+    reduced_lyrics = load_pca_model(lyrics_features)
+
+    # Scale the vectors using Z-Score
+    audio_features, reduced_lyrics = instance_scaler(audio_features, reduced_lyrics)
+
+    # Concatenate the vectors of audio_features + lyrics_features
+    results = np.concatenate([audio_features, reduced_lyrics], axis=1)
+
+    # ---- Load MLP Classifier ----
+    config = load_config("config/model_config.yml")
+    classifier = build_mlp(input_dim=results.shape[1], config=config)
+
+    # Load trained weights (make sure this path matches where you saved your model)
+    model_path = "models/mlp/mlp_multimodal.pth"
+    classifier.load_model(model_path)
+    classifier.model.eval()
+
+    # Run prediction
+    probability, prediction, label = classifier.predict_single(results)
+
+    return {
+        "probability": probability,
+        "label": label,
+        "prediction": "AI-Generated" if prediction == 0 else "Human-Composed",
+    }
+
+
+if __name__ == "__main__":
+    # Example usage (replace with real inputs, place song inside data/raw.)
+    audio = "sample"
+    lyrics = "Some lyrics text here"
+    print(predict_pipeline(audio, lyrics))

scripts/train.py

@@ -0,0 +1,160 @@
+from src.preprocessing.preprocessor import dataset_read, bulk_preprocessing
+from src.spectttra.spectttra_trainer import spectttra_train
+from src.llm2vectrain.model import load_llm2vec_model
+from src.llm2vectrain.llm2vec_trainer import l2vec_train
+from src.models.mlp import build_mlp, load_config
+
+from src.utils.config_loader import DATASET_NPZ, PCA_MODEL
+from src.utils.dataset import dataset_scaler, dataset_splitter
+from sklearn.decomposition import PCA
+
+from pathlib import Path
+import numpy as np
+import logging
+import joblib
+
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+
+def train_mlp_model(data : dict):
+    """
+    Train the MLP model with extracted features.
+    
+    Parameters
+    ----------
+        data : dict{np.array}
+            A dictionary of np.arrays, containing the train/test/val split.
+    """
+    logger.info("Starting MLP training...")
+    
+    # Load MLP configuration
+    config = load_config("config/model_config.yml")
+
+    # Destructure the dictionary to get data split
+    X_train, y_train = data["train"]
+    X_val, y_val     = data["val"]
+    X_test, y_test   = data["test"]
+    
+    # Build and train MLP
+    mlp_classifier = build_mlp(input_dim=X_train.shape[1], config=config)
+    
+    # Show model summary
+    mlp_classifier.get_model_summary()
+    
+    # Train the model
+    history = mlp_classifier.train(X_train, y_train, X_val, y_val)
+    
+    # Load best model and evaluate on test set
+    try:
+        mlp_classifier.load_model("models/mlp/mlp_best.pth")
+        logger.info("Loaded best model for final evaluation")
+    except FileNotFoundError:
+        logger.warning("Best model not found, using current model")
+    
+    # Final evaluation
+    test_results = mlp_classifier.evaluate(X_test, y_test)
+
+    # Save final model
+    mlp_classifier.save_model("models/mlp/mlp_multimodal.pth")
+    
+    logger.info("MLP training completed successfully!")
+    logger.info(f"Final test accuracy: {test_results['test_accuracy']:.2f}%")
+    
+    return mlp_classifier
+
+
+def train_pipeline():
+    """
+    Training script which includes preprocessing, feature extraction, and training the MLP model.
+
+    The train pipeline saves the train dataset in an .npz format.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    None
+    """
+
+    # Instantiate X and Y vectors
+    X, Y = None, None
+
+    dataset_path = Path(DATASET_NPZ)
+
+    if dataset_path.exists():
+        logger.info("Training dataset already exists. Loading file...")
+
+        loaded_data = np.load(DATASET_NPZ)
+        X = loaded_data["X"]
+        Y = loaded_data["Y"]
+    else:
+        logger.info("Training dataset does not exist. Processing data...")
+        # Get batches from dataset and return full Y labels
+        batches, Y = dataset_read(batch_size=500)
+        batch_count = 1
+
+        # Instantiate LLM2Vec and PCA model
+        llm2vec_model = load_llm2vec_model()
+
+        # Preallocate spaces for both audio and lyric vectors to reduce memory overhead
+        audio_vectors = np.zeros((len(Y), 384), dtype=np.float32)
+        lyric_vectors = np.zeros((len(Y), 4096), dtype=np.float32)
+
+        start_idx = 0
+        for batch in batches:
+
+            logger.info(f"Bulk Preprocessing - Batch {batch_count}.")
+            audio, lyrics = bulk_preprocessing(batch, batch_count)
+            batch_count += 1
+
+            # Call the train methods for both SpecTTTra and LLM2Vec
+            logger.info("Starting SpecTTTra feature extraction...")
+            audio_features = spectttra_train(audio)
+
+            logger.info("Starting LLM2Vec feature extraction...")
+            lyrics_features = l2vec_train(llm2vec_model, lyrics)
+
+            batch_size = audio_features.shape[0]
+
+            # Store the results on preallocated spaces
+            audio_vectors[start_idx:start_idx + batch_size, :] = audio_features
+            lyric_vectors[start_idx:start_idx + batch_size, :] = lyrics_features
+        
+            # Delete stored instance for next batch to remove overhead
+            del audio, lyrics, audio_features, lyrics_features
+
+        # Run standard scaling on audio and lyrics separately
+        logger.info("Running standard scaling for audio and lyrics...")
+        audio_vectors, lyric_vectors = dataset_scaler(audio_vectors, lyric_vectors)
+
+        # Start training the PCA to the collected lyrics features
+        logger.info("PCA Training on lyric vectors...")
+        pca = PCA(n_components=256, svd_solver="randomized", random_state=42)
+        lyric_vectors = pca.fit_transform(lyric_vectors)
+        
+        # Save the trained PCA model
+        joblib.dump(pca, "models/fusion/pca.pkl")
+
+        # Concatenate audio features and reduced lyrics features
+        X = np.concatenate([audio_vectors, lyric_vectors], axis=1)
+        logger.info(f"Audio and Lyrics Concatenated. Final features shape: {X.shape}")
+
+        # Convert label list into np.array
+        Y = np.array(Y)
+
+        # Save both X and Y to an .npz file for easier loading
+        logger.info("Saving dataset for future testing...")
+        np.savez(DATASET_NPZ, X=X, Y=Y)
+
+    # Do data splitting
+    data = dataset_splitter(X, Y)
+
+    logger.info("Starting MLP training...")
+    train_mlp_model(data)
+
+
+if __name__ == "__main__":
+    train_pipeline()

src/llm2vectrain/config.py

@@ -0,0 +1,5 @@
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+access_token = os.getenv("HF_TOKEN")

src/llm2vectrain/llm2vec_trainer.py

@@ -0,0 +1,159 @@
+from sklearn.decomposition import IncrementalPCA
+from sklearn.preprocessing import StandardScaler
+from pathlib import Path
+
+import numpy as np
+import pickle
+import torch
+import os
+import joblib
+
+# Initialize PCA and StandardScaler globally for training
+_pca_trainer = None
+
+class SimplePCATrainer:
+    """
+    A simple PCA trainer that uses IncrementalPCA to fit data in batches.
+    It saves checkpoints every 5 batches and can save the final model.
+    
+    Args:
+        None
+
+    Returns:
+        None
+
+    Attributes:
+        pca: The IncrementalPCA model.
+        scaler: StandardScaler for normalizing data.
+        fitted: Boolean indicating if the model has been initialized.
+        batch_count_pca: Counter for the number of batches processed.
+
+    Methods:
+        process_batch(vectors): Processes a batch of vectors, fits the PCA model incrementally.
+        save_final(model_path): Saves the final PCA model to the specified path.
+    """
+
+    # Initialize the trainer
+    def __init__(self):
+        self.pca = None
+        self.scaler = StandardScaler()
+        self.fitted = False
+        self.batch_count_pca = 0
+
+    def _determine_optimal_components(self, vectors):
+        """
+        Determine the optimal number of PCA components to retain 95% variance.
+        
+        Args:
+            vectors: The input data to analyze.
+        Returns:
+            n_components: The optimal number of components.
+        """
+        temp_pca = IncrementalPCA()
+        temp_pca.fit(vectors)
+        cumsum_var = np.cumsum(temp_pca.explained_variance_ratio_)
+        n_comp_95 = np.argmax(cumsum_var >= 0.95) + 1
+        return min(n_comp_95, vectors.shape[1] // 2)
+
+    def process_batch(self, vectors):
+        """
+        Process a batch of vectors, fitting the PCA model incrementally.
+        
+        Args:
+            vectors: The input data batch to process.
+        Returns:
+            reduced_vectors: The PCA-transformed data.
+
+        Note: This method saves a checkpoint every 5 batches.
+        """
+        if not self.fitted:
+            # First batch - initialize everything
+            n_components = self._determine_optimal_components(vectors)
+            self.pca = IncrementalPCA(n_components=n_components, batch_size=1000)
+            self.scaler.fit(vectors)
+            self.fitted = True
+            print(f"Initialized PCA with {n_components} components")
+
+        # Process batch
+        vectors_scaled = self.scaler.transform(vectors)
+        self.pca.partial_fit(vectors_scaled)
+        reduced_vectors = self.pca.transform(vectors_scaled)
+
+        self.batch_count_pca += 1
+
+        # Save checkpoint every 5 batches
+        if self.batch_count_pca % 5 == 0:
+            os.makedirs("pca_checkpoints", exist_ok=True)
+            with open(f"pca_checkpoints/checkpoint_batch_{self.batch_count_pca}.pkl", 'wb') as f:
+                pickle.dump({'pca': self.pca, 'scaler': self.scaler}, f)
+            print(f"Saved checkpoint at batch {self.batch_count_pca}")
+
+        print(f"Processed batch {self.batch_count_pca}, shape: {vectors.shape} -> {reduced_vectors.shape}")
+        return reduced_vectors
+
+    def save_final(self, model_path):
+        """
+        Save the final PCA model to the specified path.
+
+        Args:
+            model_path: The file path to save the PCA model.
+
+        Returns:
+            None
+        
+        Note: Change the model path as needed in the data_config.yml file.
+        """
+        os.makedirs(os.path.dirname(model_path), exist_ok=True)
+        with open(model_path, 'wb') as f:
+            pickle.dump({'pca': self.pca, 'scaler': self.scaler}, f)
+        print(f"Final model saved to {model_path}. Total variance explained: {np.sum(self.pca.explained_variance_ratio_):.4f}")
+
+## For Single Input
+def load_pca_model(vectors, model_path="models/fusion/pca.pkl"):
+    """
+    Load a pre-trained PCA model and transform the input vectors.
+
+    Args:
+        vectors: The input data to transform.
+        model_path: The file path of the pre-trained PCA model.
+
+    Returns:
+        output: The PCA-transformed data.
+
+    Note: Change the model path as needed in the data_config.yml file (or set the path file as shown above). Can be used for the main program.
+    """
+    model_path = Path(model_path)
+    pca = joblib.load(model_path)
+    return pca.transform(vectors)
+
+def l2vec_single_train(l2v, lyrics):
+    """
+    Encode a single lyric string using the provided LLM2Vec model.
+    
+    Args:
+        l2v: The LLM2Vec model for encoding lyrics.
+        lyrics: A single lyric string to encode.
+    
+    Returns:
+        vectors: The vector representation of the lyrics.
+
+    """
+    vectors = l2v.encode([lyrics]).detach().cpu().numpy()
+    return vectors
+
+# For Batch Processing
+def l2vec_train(l2v, lyrics_list):
+    """
+    Encode a list of lyric strings using the provided LLM2Vec model.
+
+    Args:
+        l2v: The LLM2Vec model for encoding lyrics.
+        lyrics_list: A list of lyric strings to encode.
+    Returns:
+        vectors: The encoded vector representations of the lyrics.
+
+    Note: This function only encodes the lyrics and does not apply PCA reduction. The PCA reduction can be applied separately in the train.py module.
+    """
+    with torch.no_grad():
+        vectors = l2v.encode(lyrics_list)  # lyrics_list: list of strings
+    return vectors

src/llm2vectrain/model.py

@@ -0,0 +1,51 @@
+from llm2vec import LLM2Vec
+from transformers import AutoTokenizer, AutoModel, AutoConfig
+from peft import PeftModel
+from src.llm2vectrain.config import access_token
+import torch
+from torchao.quantization import quantize_, Int8WeightOnlyConfig
+
+
+def load_llm2vec_model():
+
+    model_id = "McGill-NLP/LLM2Vec-Sheared-LLaMA-mntp"
+
+    tokenizer = AutoTokenizer.from_pretrained(
+        model_id, padding=True, truncation=True, max_length=512
+    )
+    config = AutoConfig.from_pretrained(model_id, trust_remote_code=True)
+
+    if torch.cuda.is_available():
+        # GPU path: use bf16 for speed
+        model = AutoModel.from_pretrained(
+            model_id,
+            trust_remote_code=True,
+            config=config,
+            torch_dtype=torch.bfloat16,
+            device_map="cuda",
+            token=access_token,
+        )
+    else:
+        # CPU path: use float32 first, then quantize
+        model = AutoModel.from_pretrained(
+            model_id,
+            trust_remote_code=True,
+            config=config,
+            torch_dtype=torch.float32,  # quantization requires fp32
+            device_map="cpu",
+            token=access_token,
+        )
+
+    try:
+        from torchao.quantization import quantize_
+
+        print("[INFO] Applying torchao quantization for CPU...")
+        quant_config = Int8WeightOnlyConfig(group_size=None)
+        print("[INFO] Applying torchao quantization with Int8WeightOnlyConfig...")
+        quantize_(model, quant_config)
+    except ImportError:
+        print("[WARNING] torchao not installed. Run: pip install torchao")
+        print("[WARNING] Falling back to non-quantized CPU model.")
+
+    l2v = LLM2Vec(model, tokenizer, pooling_mode="mean", max_length=512)
+    return l2v

src/models/mlp.py

@@ -0,0 +1,753 @@
+"""
+MLP Classifier for AI vs Human Music Detection
+==============================================
+
+This is our main classifier that determines if a piece of music was created by AI or by humans.
+
+What it does:
+- Takes combined features from LLM2Vec (text) + Spectra (audio)
+- Feeds them through a neural network
+- Outputs: "This sounds like AI" or "This sounds human"
+
+Quick Start:
+---------------------------
+# 1. Load settings from config file
+config = load_config("config/model_config.yml")
+
+# 2. Combine LLM2Vec and Spectra features
+combined_features = np.concatenate([llm2vec_features, spectra_features], axis=1)
+
+# 3. Create classifier
+classifier = MLPClassifier(input_dim=combined_features.shape[1], config=config)
+
+# 4. Train it
+history = classifier.train(X_train, y_train, X_val, y_val)
+
+# 5. Test it
+results = classifier.evaluate(X_test, y_test)
+
+# 6. Use it for new predictions
+probabilities, predictions = classifier.predict(new_music_features)
+
+How the Neural Network Works:
+-----------------------------
+Input → Hidden Layers → Output
+  ↓         ↓           ↓
+Features  Processing  AI/Human
+(LLM2Vec + (Multiple   (0 or 1)
+ Spectra)   layers)
+
+The network learns patterns that help distinguish AI-generated music from human music.
+"""
+
+from typing import Dict, Tuple
+from pathlib import Path
+from tqdm import tqdm
+from torch.utils.data import DataLoader, TensorDataset
+from sklearn.metrics import classification_report, confusion_matrix
+
+import logging
+import torch
+import torch.nn as nn
+import torch.optim as optim
+import numpy as np
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+class MLPModel(nn.Module):
+    """
+    The actual neural network that does the AI vs Human classification.
+
+    What happens inside:
+    1. Takes the combined LLM2Vec + Spectra features
+    2. Passes them through multiple hidden layers (each layer learns different patterns)
+    3. Each layer applies: processing → normalization → activation → dropout
+    4. Final layer outputs a probability (0-1) where closer to 1 = "more human-like"
+
+    Args:
+        input_dim (int): How many features we have total (LLM2Vec size + Spectra size)
+        config (Dict): Settings from the YAML file that specify:
+            - "hidden_layers": How many neurons in each layer [128, 64, 32]
+            - "dropout": How much to randomly "forget" to prevent overfitting [0.3, 0.5, 0.2]
+    """
+
+    def __init__(self, input_dim: int, config: Dict):
+        """
+        Build the neural network architecture based on our config file.
+        """
+        super(MLPModel, self).__init__()
+
+        self.hidden_layers = config["hidden_layers"]
+        self.dropout_rates = config["dropout"]
+
+        # Build layers with batch normalization
+        layers = []
+        prev_dim = input_dim
+
+        # First, normalize the input features (makes training more stable)
+        layers.append(nn.BatchNorm1d(input_dim))
+
+        # Build hidden layers
+        for i, units in enumerate(self.hidden_layers):
+            # Main processing layer
+            layers.append(nn.Linear(prev_dim, units))
+
+            # Normalize outputs (helps with training stability)
+
+            # Batch normalization
+            layers.append(nn.BatchNorm1d(units))
+
+            # Activation function (allows network to learn complex patterns)
+            layers.append(nn.LeakyReLU(negative_slope=0.01))
+
+            # Randomly "forget" some connections to prevent overfitting
+            dropout_rate = self.dropout_rates[i] if i < len(self.dropout_rates) else 0.5
+            if dropout_rate > 0:
+                layers.append(nn.Dropout(dropout_rate))
+
+            prev_dim = units
+
+        # Final output layer: gives us the AI vs Human probability
+        layers.append(nn.Linear(prev_dim, 1))
+        # Squeezes output between 0 and 1
+        layers.append(nn.Sigmoid())
+
+        self.network = nn.Sequential(*layers)
+        self._initialize_weights()
+
+        logger.info(
+            f"Built MLP with {len(self.hidden_layers)} hidden layers: {self.hidden_layers}"
+        )
+
+    def _initialize_weights(self):
+        """
+        Set up the starting weights for training.
+
+        Uses Xavier initialization - a way to set initial weights
+        so the network trains better from the start.
+        """
+        for layer in self.network:
+            if isinstance(layer, nn.Linear):
+                nn.init.xavier_uniform_(layer.weight, gain=0.5)
+                nn.init.zeros_(layer.bias)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Process input features through the network to get predictions.
+
+        Args:
+            x: Our combined music features (LLM2Vec + Spectra)
+
+        Returns:
+            Probability that the music is human-composed (0 to 1)
+        """
+        return self.network(x)
+
+    def mixup(X, y, alpha=0.2):
+        """Apply MixUp augmentation to a batch."""
+        if alpha <= 0:
+            return X, y, y, 1.0  # no mixing
+
+        lam = np.random.beta(alpha, alpha)
+        batch_size = X.size(0)
+        index = torch.randperm(batch_size).to(X.device)
+
+        mixed_X = lam * X + (1 - lam) * X[index]
+        y_a, y_b = y, y[index]
+        return mixed_X, y_a, y_b, lam
+
+    def mixup_loss(criterion, pred, y_a, y_b, lam):
+        """Compute MixUp loss."""
+        return lam * criterion(pred, y_a) + (1 - lam) * criterion(pred, y_b)
+
+
+class MLPClassifier:
+    """
+    The complete music classifier system that wraps everything together.
+
+    This handles all the training, testing, and prediction logic.
+
+    What it manages:
+    - The neural network model
+    - Training process (with smart features like early stopping)
+    - Making predictions on new music
+    - Saving/loading trained models
+    """
+
+    def __init__(self, input_dim: int, config: Dict):
+        """
+        Set up the complete classification system.
+
+        Args:
+            input_dim (int): Total number of features (LLM2Vec + Spectra combined)
+            config (Dict): All our settings from the YAML config file
+
+        This creates:
+        - The neural network
+        - The training optimizer (Adam - good for most cases)
+        - Learning rate scheduler (automatically adjusts learning speed)
+        - Loss function (measures how wrong our predictions are)
+        """
+        self.config = config
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+        # Build the neural network
+        self.model = MLPModel(input_dim, config).to(self.device)
+
+        # Optimizer: the algorithm that improves the network during training
+        self.optimizer = optim.Adam(
+            self.model.parameters(),
+            lr=config.get("learning_rate", 0.001),
+            weight_decay=config.get("weight_decay", 0.01),
+        )
+
+        # Scheduler: automatically reduces learning rate if we get stuck
+        self.scheduler = optim.lr_scheduler.ReduceLROnPlateau(
+            self.optimizer, mode="min", factor=0.5, patience=5, min_lr=1e-7
+        )
+
+        # Loss function: measures how wrong our predictions are
+        self.criterion = nn.BCELoss()
+
+        self.is_trained = False
+
+        logger.info(f"Using device: {self.device}")
+        logger.info(
+            f"Model parameters: {sum(p.numel() for p in self.model.parameters()):,}"
+        )
+
+    def _create_data_loader(
+        self, X: np.ndarray, y: np.ndarray, shuffle: bool = True
+    ) -> DataLoader:
+        """
+        Convert the numpy arrays into batches that PyTorch can process.
+        """
+        X_tensor = torch.FloatTensor(X)
+        y_tensor = torch.FloatTensor(y).unsqueeze(1)
+
+        dataset = TensorDataset(X_tensor, y_tensor)
+        return DataLoader(
+            dataset, batch_size=self.config["batch_size"], shuffle=shuffle
+        )
+
+    def train(
+        self,
+        X_train: np.ndarray,
+        y_train: np.ndarray,
+        X_val: np.ndarray,
+        y_val: np.ndarray,
+    ) -> Dict:
+        """
+        Train the model to recognize AI vs Human music patterns.
+
+        The model learns by:
+        1. Looking at training examples (music + labels)
+        2. Making predictions
+        3. Seeing how wrong it was
+        4. Adjusting its parameters to do better
+        5. Repeating thousands of times
+
+        Args:
+            X_train: Training music features (LLM2Vec + Spectra combined)
+            y_train: Training labels (0 = AI-generated, 1 = human-composed)
+            X_val: Validation features (used to check if we're overfitting)
+            y_val: Validation labels
+
+        Returns:
+            Dict: Training history showing how loss and accuracy changed over time
+
+        Smart features included:
+        - Early stopping: stops training if validation performance gets worse
+        - Learning rate scheduling: slows down learning if we get stuck
+        - Gradient clipping: prevents training from going crazy
+        - Progress bars: so we can see what's happening. imported tqdm for this LMAO
+        """
+        logger.info("Starting MLP training...")
+
+        # Prepare the data for training
+        train_loader = self._create_data_loader(X_train, y_train, shuffle=True)
+        val_loader = self._create_data_loader(X_val, y_val, shuffle=False)
+
+        # Track training progress
+        history = {"train_loss": [], "train_acc": [], "val_loss": [], "val_acc": []}
+
+        # Early stopping variables
+        best_val_loss = float("inf")
+        patience_counter = 0
+        patience = self.config["patience"]
+
+        # Main training loop
+        for epoch in range(self.config["epochs"]):
+            # Training phase - model learns from training data
+            self.model.train()
+            train_loss = 0.0
+            train_correct = 0
+            train_total = 0
+
+            train_pbar = tqdm(
+                train_loader, desc=f"Epoch {epoch+1}/{self.config['epochs']} [Train]"
+            )
+            for batch_X, batch_y in train_pbar:
+                batch_X, batch_y = batch_X.to(self.device), batch_y.to(self.device)
+
+                # Forward pass: make predictions
+                self.optimizer.zero_grad()
+
+                # Adding training augmentation if mixup value > 0
+                if self.config.get("mixup_alpha", 0) > 0:
+                    mixed_X, y_a, y_b, lam = MLPModel.mixup(
+                        batch_X, batch_y, alpha=self.config["mixup_alpha"]
+                    )
+                    outputs = self.model(mixed_X)
+                    loss = MLPModel.mixup_loss(self.criterion, outputs, y_a, y_b, lam)
+                else:
+                    outputs = self.model(batch_X)
+                    loss = self.criterion(outputs, batch_y)
+
+                # Backward pass: learn from mistakes
+                loss.backward()
+
+                # Prevent gradients from getting too large (helps stability)
+                if self.config.get("gradient_clipping"):
+                    torch.nn.utils.clip_grad_norm_(
+                        self.model.parameters(), self.config["gradient_clipping"]
+                    )
+
+                self.optimizer.step()
+
+                # Track statistics
+                train_loss += loss.item()
+                # Convert probabilities to 0/1 predictions
+                predicted = (outputs > 0.5).float()
+                train_total += batch_y.size(0)
+                train_correct += (predicted == batch_y).sum().item()
+
+                # Update progress bar
+                train_pbar.set_postfix(
+                    {
+                        "Loss": f"{loss.item():.4f}",
+                        "Acc": f"{100.*train_correct/train_total:.2f}%",
+                    }
+                )
+
+            # Calculate epoch averages
+            avg_train_loss = train_loss / len(train_loader)
+            train_acc = 100.0 * train_correct / train_total
+
+            history["train_loss"].append(avg_train_loss)
+            history["train_acc"].append(train_acc)
+
+            # Validation phase - check how well we do on unseen data
+            val_loss, val_acc = self._validate(val_loader)
+            history["val_loss"].append(val_loss)
+            history["val_acc"].append(val_acc)
+
+            # Adjust learning rate if needed
+            self.scheduler.step(val_loss)
+
+            logger.info(
+                f"Epoch {epoch+1}: Train Loss: {avg_train_loss:.4f}, Train Acc: {train_acc:.2f}%, "
+                f"Val Loss: {val_loss:.4f}, Val Acc: {val_acc:.2f}%"
+            )
+
+            # Early stopping logic - save best model and stop if no improvement
+            if val_loss < best_val_loss:
+                best_val_loss = val_loss
+                patience_counter = 0
+                self.is_trained = True
+                # Save the best version
+                self.save_model("models/mlp/mlp_best.pth")
+            else:
+                patience_counter += 1
+
+            if patience_counter >= patience:
+                logger.info(f"Early stopping triggered after {epoch+1} epochs")
+                break
+
+        self.is_trained = True
+        logger.info("MLP training completed!")
+        return history
+
+    def _validate(self, val_loader: DataLoader) -> Tuple[float, float]:
+        """
+        Test how well the model performs on validation/test data.
+
+        This runs the model in "evaluation mode" - no learning happens,
+        we just check how accurate our predictions are.
+
+        Returns:
+            Average loss and accuracy percentage
+        """
+        # Switch to evaluation mode
+        self.model.eval()
+        val_loss = 0.0
+        val_correct = 0
+        val_total = 0
+
+        # Don't track gradients (saves memory and time)
+        with torch.no_grad():
+            for batch_X, batch_y in val_loader:
+                batch_X, batch_y = batch_X.to(self.device), batch_y.to(self.device)
+
+                outputs = self.model(batch_X)
+                loss = self.criterion(outputs, batch_y)
+
+                val_loss += loss.item()
+                # Convert to binary predictions
+                predicted = (outputs > 0.5).float()
+                val_total += batch_y.size(0)
+                val_correct += (predicted == batch_y).sum().item()
+
+        avg_val_loss = val_loss / len(val_loader)
+        val_acc = 100.0 * val_correct / val_total
+
+        return avg_val_loss, val_acc
+
+    def predict(self, X: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Use the trained model to classify new music as AI-generated or human-composed.
+
+        Args:
+            X: Music features (LLM2Vec + Spectra combined) for songs we want to classify
+
+        Returns:
+            probabilities: How confident the model is (0.0 to 1.0, higher = more human-like)
+            predictions: Binary classifications (0 = AI-generated, 1 = human-composed)
+
+        Example:
+            probs, preds = classifier.predict(new_song_features)
+            if preds[0] == 1:
+                print(f"This sounds human-composed (confidence: {probs[0]:.2f})")
+            else:
+                print(f"This sounds AI-generated (confidence: {1-probs[0]:.2f})")
+        """
+        self.model.eval()
+        # Create dummy labels since we don't know the true answers
+        data_loader = self._create_data_loader(X, np.zeros(len(X)), shuffle=False)
+
+        probabilities = []
+
+        with torch.no_grad():
+            for batch_X, _ in data_loader:
+                batch_X = batch_X.to(self.device)
+                outputs = self.model(batch_X)
+                probabilities.extend(outputs.cpu().numpy())
+
+        probabilities = np.array(probabilities).flatten()
+        # Threshold at 0.5
+        predictions = (probabilities > 0.5).astype(int)
+
+        return probabilities, predictions
+
+    def predict_single(self, features: np.ndarray) -> Tuple[float, int, str]:
+        """
+        Predict whether a single song is AI-generated or human-composed.
+
+        This method is optimized for predicting one song at a time.
+
+        Args:
+            features: Music features for ONE song (LLM2Vec + Spectra combined)
+                    Should be 1D array with shape (feature_dim,)
+
+        Returns:
+            probability: Confidence score (0.0 to 1.0, higher = more human-like)
+            prediction: Binary classification (0 = AI-generated, 1 = human-composed)
+            label: Human-readable label ("AI-Generated" or "Human-Composed")
+
+        Example:
+            # For a single song
+            single_song_features = np.array([0.1, 0.5, 0.3, ...])
+            prob, pred, label = classifier.predict_single(single_song_features)
+
+            print(f"Prediction: {label}")
+            print(f"Confidence: {prob:.3f}")
+
+            if pred == 1:
+                print(f"This sounds {prob:.1%} human-composed")
+            else:
+                print(f"This sounds {(1-prob):.1%} AI-generated")
+        """
+        if not self.is_trained:
+            raise ValueError(
+                "Model must be trained before making predictions. Call train() first."
+            )
+
+        # Ensure input is the right shape
+        if features.ndim == 1:
+            features = features.reshape(1, -1)  # Convert to batch of size 1
+        elif features.shape[0] != 1:
+            raise ValueError(
+                f"Expected features for 1 song, got {features.shape[0]} songs. Use predict_batch() instead."
+            )
+
+        # Use the existing predict method
+        probabilities, predictions = self.predict(features)
+
+        # Extract single results
+        probability = float(probabilities[0])
+        prediction = int(predictions[0])
+        label = "Human-Composed" if prediction == 1 else "AI-Generated"
+
+        return probability, prediction, label
+
+    def predict_batch(self, features: np.ndarray, return_details: bool = False) -> Dict:
+        """
+        Predict AI vs Human classification for multiple songs at once.
+
+        This method is optimized for batch processing - much faster than calling
+        predict_single() multiple times.
+
+        Args:
+            features: Music features for MULTIPLE songs (LLM2Vec + Spectra combined)
+                    Should be 2D array with shape (num_songs, feature_dim)
+            return_details: If True, includes additional statistics and breakdowns
+
+        Returns:
+            Dictionary containing:
+            - 'probabilities': Confidence scores for each song (0.0 to 1.0)
+            - 'predictions': Binary classifications (0 = AI, 1 = Human)
+            - 'labels': Human-readable labels for each song
+            - 'summary': Quick stats about the batch results
+            - 'details': (if return_details=True) Additional analysis
+
+        Example:
+            # For multiple songs
+            batch_features = np.array([[0.1, 0.5, 0.3, ...], # Song 1
+                                    [0.2, 0.4, 0.7, ...],    # Song 2
+                                    [0.3, 0.6, 0.1, ...]])   # Song 3
+
+            results = classifier.predict_batch(batch_features, return_details=True)
+
+            print(f"Processed {len(results['predictions'])} songs")
+            print(f"Summary: {results['summary']}")
+
+            for i, (prob, pred, label) in enumerate(zip(results['probabilities'],
+                                                    results['predictions'],
+                                                    results['labels'])):
+                print(f"Song {i+1}: {label} (confidence: {prob:.3f})")
+        """
+        if not self.is_trained:
+            raise ValueError(
+                "Model must be trained before making predictions. Call train() first."
+            )
+
+        # Ensure input is 2D
+        if features.ndim == 1:
+            raise ValueError(
+                "For batch prediction, features should be 2D (num_songs, feature_dim). "
+                "For single song, use predict_single() instead."
+            )
+
+        num_songs = features.shape[0]
+        logger.info(f"Processing batch of {num_songs} songs...")
+
+        # Get predictions using existing method
+        probabilities, predictions = self.predict(features)
+
+        # Convert to human-readable labels
+        labels = [
+            "Human-Composed" if pred == 1 else "AI-Generated" for pred in predictions
+        ]
+
+        # Calculate summary statistics
+        num_human = np.sum(predictions == 1)
+        num_ai = np.sum(predictions == 0)
+        avg_confidence_human = (
+            np.mean(probabilities[predictions == 1]) if num_human > 0 else 0.0
+        )
+        avg_confidence_ai = (
+            np.mean(1 - probabilities[predictions == 0]) if num_ai > 0 else 0.0
+        )
+
+        summary = {
+            "total_songs": num_songs,
+            "human_composed": num_human,
+            "ai_generated": num_ai,
+            "human_percentage": (num_human / num_songs) * 100,
+            "ai_percentage": (num_ai / num_songs) * 100,
+            "avg_confidence_human": avg_confidence_human,
+            "avg_confidence_ai": avg_confidence_ai,
+        }
+
+        results = {
+            "probabilities": probabilities,
+            "predictions": predictions,
+            "labels": labels,
+            "summary": summary,
+        }
+
+        # Add detailed analysis if requested
+        if return_details:
+            # Confidence distribution analysis
+            high_confidence = np.sum((probabilities > 0.8) | (probabilities < 0.2))
+            medium_confidence = np.sum(
+                (probabilities >= 0.6) & (probabilities <= 0.8)
+                | (probabilities >= 0.2) & (probabilities <= 0.4)
+            )
+            low_confidence = np.sum((probabilities > 0.4) & (probabilities < 0.6))
+
+            # Most confident predictions
+            sorted_indices = np.argsort(np.abs(probabilities - 0.5))[
+                ::-1
+            ]  # Most confident first
+            most_confident_indices = sorted_indices[: min(5, len(sorted_indices))]
+            least_confident_indices = sorted_indices[-min(5, len(sorted_indices)) :]
+
+            details = {
+                "confidence_distribution": {
+                    "high_confidence": high_confidence,
+                    "medium_confidence": medium_confidence,
+                    "low_confidence": low_confidence,
+                },
+                "most_confident_predictions": {
+                    "indices": most_confident_indices.tolist(),
+                    "probabilities": probabilities[most_confident_indices].tolist(),
+                    "predictions": predictions[most_confident_indices].tolist(),
+                },
+                "least_confident_predictions": {
+                    "indices": least_confident_indices.tolist(),
+                    "probabilities": probabilities[least_confident_indices].tolist(),
+                    "predictions": predictions[least_confident_indices].tolist(),
+                },
+                "probability_stats": {
+                    "mean": float(np.mean(probabilities)),
+                    "std": float(np.std(probabilities)),
+                    "min": float(np.min(probabilities)),
+                    "max": float(np.max(probabilities)),
+                    "median": float(np.median(probabilities)),
+                },
+            }
+            results["details"] = details
+
+        logger.info(
+            f"Batch prediction completed: {num_human} human, {num_ai} AI-generated"
+        )
+        return results
+
+    def evaluate(self, X_test: np.ndarray, y_test: np.ndarray) -> Dict[str, float]:
+        """
+        Get detailed performance metrics on test data.
+
+        This gives us the final report card for our model:
+        - How accurate is it overall?
+        - How well does it detect AI-generated music?
+        - How well does it detect human-composed music?
+        - What kinds of mistakes does it make?
+
+        Args:
+            X_test: Test music features
+            y_test: True labels (0 = AI, 1 = Human)
+
+        Returns:
+            Dictionary with test loss and accuracy
+
+        Also logs detailed reports including:
+        - Precision, recall, F1-score for each class
+        - Confusion matrix showing prediction vs reality
+        """
+        probabilities, predictions = self.predict(X_test)
+
+        test_loader = self._create_data_loader(X_test, y_test, shuffle=False)
+        test_loss, test_acc = self._validate(test_loader)
+
+        results = {"test_loss": test_loss, "test_accuracy": test_acc}
+        logger.info(f"Test Results: {results}")
+
+        # Detailed performance breakdown
+        report = classification_report(
+            y_test, predictions, target_names=["AI-Generated", "Human-Composed"]
+        )
+        logger.info(f"Classification Report:\n{report}")
+
+        # Confusion matrix: shows what the model confused
+        cm = confusion_matrix(y_test, predictions)
+        logger.info(f"Confusion Matrix:\n{cm}")
+
+        return results
+
+    def save_model(self, filepath: str) -> None:
+        """
+        Save our trained model so we can use it later.
+
+        Args:
+            filepath: Where to save the model
+
+        Saves everything needed to reload the model:
+        - The learned weights
+        - Training settings
+        - Optimizer state
+        """
+        Path(filepath).parent.mkdir(parents=True, exist_ok=True)
+        torch.save(
+            {
+                "model_state_dict": self.model.state_dict(),
+                "optimizer_state_dict": self.optimizer.state_dict(),
+                "config": self.config,
+                "is_trained": self.is_trained,
+            },
+            filepath,
+        )
+        logger.info(f"Model saved to {filepath}")
+
+    def load_model(self, filepath: str) -> None:
+        """
+        Load a previously trained model.
+
+        Args:
+            filepath: Path to our saved model file
+
+        After this, you can immediately use predict() and evaluate()
+        without needing to train again.
+        """
+        checkpoint = torch.load(filepath, map_location=self.device)
+        self.model.load_state_dict(checkpoint["model_state_dict"])
+        self.optimizer.load_state_dict(checkpoint["optimizer_state_dict"])
+        self.config = checkpoint["config"]
+        self.is_trained = checkpoint.get("is_trained", True)
+        logger.info(f"Model loaded from {filepath}")
+
+        # Temporary override, while waiting for bigger dataset and for model to be trained at that
+        self.is_trained = True
+
+    def get_model_summary(self) -> None:
+        """
+        Print out details about our model architecture.
+
+        Useful for debugging or understanding what we've built.
+        Shows the network structure and how many parameters it has.
+        """
+        logger.info("Model Architecture:")
+        logger.info(self.model)
+        total_params = sum(p.numel() for p in self.model.parameters())
+        logger.info(f"Total parameters: {total_params:,}")
+
+
+def build_mlp(input_dim: int, config: Dict) -> MLPClassifier:
+    """
+    Quick way to create an MLP classifier.
+
+    Args:
+        input_dim: Size of our combined features (LLM2Vec + Spectra)
+        config: Our model settings from the YAML file
+
+    Returns:
+        Ready-to-use MLPClassifier instance
+    """
+    return MLPClassifier(input_dim, config)
+
+
+def load_config(config_path: str = "config/model_config.yml") -> Dict:
+    """
+    Load our model settings from the YAML configuration file.
+
+    Args:
+        config_path: Path to our config file
+
+    Returns:
+        Dictionary with all our MLP settings (hidden layers, dropout, etc.)
+    """
+    with open(config_path, "r") as f:
+        config = yaml.safe_load(f)
+    return config["mlp"]