Models
======

This module contains functions for model definitions, prediction, saving, training, and tuning.

Model Definitions
-----------------

.. automodule:: emotion_detective.models.model_definitions
   :members:
   :undoc-members:
   :show-inheritance:

   - **roberta_model**: Creates a classification model using the Roberta architecture.
   - **rnn_model**: Creates a classification model using the RNN architecture.
   - **load_model**: Loads a pre-trained model from the specified path.

   .. code-block:: python

      from emotion_detective.models.model_definitions import create_model, roberta_model, rnn_model

      # Example usage
      roberta = roberta_model(num_labels=7)
      rnn = rnn_model(num_labels=7, embedding_dim=128, hidden_dim=256)
      loaded_model = load_model(model_path='path/to/model.pth')

Troubleshooting
~~~~~~~~~~~~~~~

   - **roberta_model**: 
     - Ensure that the "roberta-base" model is available and correctly specified.
     - Check for sufficient memory resources.
     - Verify internet connectivity if downloading the model.
     - If an error occurs, inspect the log for detailed error messages.
     - Example code snippet for troubleshooting:

       .. code-block:: python

          try:
              model = roberta_model(num_labels=6)
          except Exception as e:
              print("Error:", e)

   - **rnn_model**:
      - Ensure that the tokenizer (bert-base-uncased) is available and correctly specified.
      - Check for sufficient memory resources, especially if using large embedding or hidden dimensions.
      - Verify internet connectivity if downloading tokenizer or embeddings.
      - If an error occurs, inspect the log for detailed error messages.
      - Example code snippet for troubleshooting:

    .. code-block:: python

      try:
         model = rnn_model(num_labels=6, embedding_dim=128, hidden_dim=256)
      except Exception as e:
         print("Error:", e)

   - **load_model**: 
     - Confirm the model path is correct and accessible.
     - Ensure the file format matches the expected format '.pth'.
     - If an error occurs, inspect the log for detailed error messages.
     - Example code snippet for troubleshooting:

       .. code-block:: python

          try:
              loaded_model = load_model(model_path='path/to/model.pth')
          except Exception as e:
              print("Error:", e)

Model Prediction
----------------

.. automodule:: emotion_detective.models.model_predict
   :members:
   :undoc-members:
   :show-inheritance:

   - **get_predictions**: Obtain predictions from a model based on the input DataFrame.

   .. code-block:: python

      from emotion_detective.models.model_predict import get_predictions

      # Example usage
      predictions_df = get_predictions(model_path, df, emotion_mapping_path='path/to/mapping.json', model_type='roberta')

Troubleshooting
~~~~~~~~~~~~~~~

   - **get_predictions**:
     - Verify that the input DataFrame is correctly formatted.
     - Ensure the model is in evaluation mode.
     - Make sure the data loader is working correctly.
     - If an error occurs, inspect the log for detailed error messages.
     - Example code snippet for troubleshooting:

       .. code-block:: python

          try:
              predictions_df = get_predictions(model, df, emotion_mapping_path='path/to/mapping.json', model_type='roberta')
          except Exception as e:
              print("Error:", e)

Model Saving
------------

.. automodule:: emotion_detective.models.model_saving
   :members:
   :undoc-members:
   :show-inheritance:

   - **save_model**: Saves the state of a PyTorch model to a binary file.

   .. code-block:: python

      from emotion_detective.models.model_saving import save_model

      # Example usage
      save_model(model, model_dir='models', model_name='my_model')

Troubleshooting
~~~~~~~~~~~~~~~

   - **save_model**:
     - Confirm the directory path exists or can be created.
     - Check file permissions for writing.
     - Ensure the model is properly instantiated and not None.
     - If an error occurs, inspect the log for detailed error messages.
     - Example code snippet for troubleshooting:

       .. code-block:: python

          try:
              save_model(model, model_dir='models', model_name='my_model')
          except Exception as e:
              print("Error:", e)

Model Training
--------------

.. automodule:: emotion_detective.models.model_training
   :members:
   :undoc-members:
   :show-inheritance:

   - **train_and_evaluate_roberta**: Trains and evaluates a neural network model for emotion detection based on the roberta model architecture.
   - **train_and_evaluate_rnn**: Trains and evaluates a neural network model for emotion detection based on the RNN model architecture.
   
   .. code-block:: python

      from emotion_detective.models.model_training import train_and_evaluate_roberta, train_and_evaluate_rnn
      import pandas as pd

      # Train and evaluate RoBERTa Example usage
      trained_model, evaluation_results = train_and_evaluate_roberta(
         roberta_model=roberta_model,
         train_data=train_data,
         test_data=test_data,
         output_dir='./roberta_output/',
         logging_dir='./logs/',
         num_train_epochs=3,
         train_batch_size=4,
         eval_batch_size=8,
         gradient_accumulation_steps=16,
         learning_rate=2e-5,
         warmup_steps=500,
         weight_decay=0.01,
         logging_steps=8,
         disable_tqdm=False,
         dataloader_num_workers=8,
         seed=42,
         early_stopping_patience=3,
         cloud_logging=True
      )

      # Print evaluation results
      print("Evaluation results:", evaluation_results)

      # Train and evaluate RNN Example usage
      trained_rnn_model = train_and_evaluate_rnn(
         model=rnn_model,
         train_data=train_data,
         test_data=test_data,
         num_epochs=5,
         early_stopping_patience=3,
         learning_rate=0.001,
         train_batch_size=4,
         eval_batch_size=8,
         cloud_logging=True
      )

Troubleshooting
~~~~~~~~~~~~~~~

   - **train_and_evaluate_roberta**:
      - Model Training Issues: If the model fails to train, check the batch sizes (train_batch_size, eval_batch_size), and gradient_accumulation_steps settings. Adjusting these parameters can help resolve memory issues or improve training stability.
      - Logging Errors: If logging fails (e.g., with MLflow), ensure the logging directories (output_dir, logging_dir) are accessible and have write permissions. Also, verify that MLflow is correctly configured and running.
      - Performance Metrics: If the evaluation metrics are unexpected, ensure that compute_metrics function correctly computes metrics relevant to your task. Check if the labels and predictions are aligned properly in compute_metrics.

   - **train_and_evaluate_rnn**:
      - Tokenization Errors: If tokenization fails, ensure BertTokenizer (or equivalent) is correctly initialized and that text lengths are within tokenizer limits (max_length). Adjust tokenize function parameters accordingly.
      - Training Convergence: If the model does not converge or loss does not decrease, check learning_rate and consider adjusting it. Also, monitor training and validation losses (train_loss, eval_loss) to ensure they are reasonable and decreasing over epochs.
      - Early Stopping: If early stopping triggers unexpectedly or too early, review early_stopping_patience and eval_loss monitoring. Adjust these parameters based on model convergence patterns observed during training.