API Reference¶

Backend API Endpoints¶

All endpoints are at: http://localhost:8000

All endpoints require no authentication and no query parameters.

Root Endpoint¶

GET /

Description: Returns a simple connection message to verify the backend API is accessible.

When to use: Use this endpoint to verify that the backend server is running and accessible before making other API calls.

Response:

{
    "message": "Backend is connected!"
}

Health Check¶

GET /health

Description: Returns the health status of the backend API server.

When to use: Use this endpoint to check if the backend is running properly, typically for monitoring or health checks in production environments.

Response:

{
    "status": "ok",
    "detail": "Backend is connected and running fine."
}

Upload Dataset¶

POST /upload

Description: Uploads a pickle file containing a 5D dataset, stores it, and preprocesses the data into train/validation/test splits.

When to use: Use this endpoint as the first step in the workflow to upload your dataset before training a model. The dataset must be a pickle file containing a dictionary with keys “X” (features), “y” (targets), and “metadata”.

Request Body: multipart/form-data with file upload

The file must contain a dictionary with keys:

“X”: numpy array of features (n_samples, 5)
“y”: numpy array of targets (n_samples,)
“metadata”: dict with “feature_names” (list) and “target_name” (str)

Response (Success):

{
    "status": "success",
    "message": "Pickle dataset uploaded, stored, and preprocessed",
    "filename": "data.pkl",
    "num_points": 5000,
    "num_features": 5,
    "target_range": {
        "min": -1.14,
        "max": 1.63
    },
    "train_size": 3500,
    "val_size": 750,
    "test_size": 750
}

Response (Error - Invalid file type):

{
    "status": "error",
    "message": "Only pickle files (.pkl, .pickle) are allowed."
}

Response (Error - Failed to save):

{
    "status": "error",
    "message": "Failed to save pickle file: <error details>"
}

Response (Error - Failed to load):

{
    "status": "error",
    "message": "Failed to load pickle: <error details>"
}

Response (Error - Preprocessing failed):

{
    "status": "error",
    "message": "Data preprocessing failed: <error details>"
}

Train Model¶

POST /train

Description: Trains a neural network model using the uploaded and preprocessed dataset with specified hyperparameters.

When to use: Use this endpoint after uploading a dataset via /upload to train a neural network model. You can customize the architecture (number of layers, neurons per layer), training epochs, and learning rate.

Request Body (JSON):

{
    "epochs": 100,
    "learning_rate": 0.001,
    "hidden_layers": [64, 32]
}

Request Body Parameters:

epochs (int, required): Number of training epochs (typically 5-200)
learning_rate (float, optional): Learning rate for the optimizer (default: 0.001, range: 0.0001-0.001)
hidden_layers (List[int], optional): List of neurons per hidden layer (default: [64, 32])

Response (Success):

{
    "status": "success",
    "message": "Model trained for 100 epochs",
    "mse": 0.0197,
    "r2": 0.9335,
    "train_size": 3500,
    "val_size": 750,
    "test_size": 750,
    "model_path": "/outputs/model.pkl",
    "training_time_seconds": 0.55,
    "learning_curve_url": "/outputs/learning_curve.png",
    "predictions_plot_url": "/outputs/predictions_plot.png"
}

Response (Error - No data):

{
    "status": "error",
    "message": "Training failed. No preprocessed dataset found."
}

Response (Error - Training failed):

{
    "status": "error",
    "message": "Training failed: <error details>"
}

Make Prediction¶

POST /predict

Description: Generates a prediction for a given 5-dimensional input using the trained neural network model.

When to use: Use this endpoint after training a model via /train to make predictions for new input values. Provide 5 input values (x1, x2, x3, x4, x5) and receive a predicted output value.

Request Body (JSON):

{
    "inputs": [0.5, 0.5, 0.5, 0.5, 0.5]
}

Request Body Parameters:

inputs (List[float], required): List of exactly 5 input values [x1, x2, x3, x4, x5] (each value typically in range 0.0-1.0)

Response (Success):

{
    "status": "success",
    "inputs": [0.5, 0.5, 0.5, 0.5, 0.5],
    "prediction": 0.59
}

Response (Error - No model):

{
    "status": "error",
    "message": "No trained model found. Please train the model first via /train endpoint."
}

Response (Error - Prediction failed):

{
    "status": "error",
    "message": "Prediction failed: <error details>"
}

Reset¶

POST /reset

Description: Clears all uploaded files from the uploads and outputs directories and resets the application state to start fresh with a new dataset.

When to use: Use this endpoint when you want to start over with a new dataset or clear all previous training results. This removes all uploaded files, trained models, and generated plots.

Response:

{
    "status": "success",
    "removed": {
        "uploads": ["data.pkl"],
        "outputs": ["model.pkl", "learning_curve.png", "predictions_plot.png"]
    }
}