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:**

.. code-block:: json

   {
       "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:**

.. code-block:: json

   {
       "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):**

.. code-block:: json

   {
       "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):**

.. code-block:: json

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

**Response (Error - Failed to save):**

.. code-block:: json

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

**Response (Error - Failed to load):**

.. code-block:: json

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

**Response (Error - Preprocessing failed):**

.. code-block:: json

   {
       "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):**

.. code-block:: 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):**

.. code-block:: json

   {
       "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):**

.. code-block:: json

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

**Response (Error - Training failed):**

.. code-block:: json

   {
       "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):**

.. code-block:: 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):**

.. code-block:: json

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

**Response (Error - No model):**

.. code-block:: json

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

**Response (Error - Prediction failed):**

.. code-block:: json

   {
       "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:**

.. code-block:: json

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