docs(examples): updated example directory and README

README.md

@@ -29,12 +29,6 @@
 
 Bundling your machine learning model with VerySimpleTransformers is straightforward. Follow these steps:
 
-Import the necessary modules and functions:
-
-```python
-from verysimpletransformers import to_vst
-```
-
 Create or load your machine learning model (e.g., a ClassificationModel) using Simple Transformers.
 
 Example:
@@ -60,7 +54,8 @@ model.train_model(...)
 
 ```
 
-Use the `to_vst` function to package the model into a .vst file with optional compression.
+Import the `verysimpletransformers` package, and use the `to_vst` function to package the model into a .vst file with
+optional compression.
 
 Provide the model, the output file path, and an optional compression level (0-9).
 By default, compression will be disabled.
@@ -74,12 +69,13 @@ The output file path can be specified as:
 Example:
 
 ```python
-from pathlib import Path
+import verysimpletransformers  # or: from verysimpletransformers import to_vst
+from pathlib import Path  # can be used instead of a string
 
-to_vst(model,
-       "my_model.vst",
-       compression=5,  # optional
-       )
+verysimpletransformers.to_vst(model,
+                              "my_model.vst",
+                              compression=5,  # optional
+                              )
 ```
 
 Note: As an alias, `bundle_model` can be used instead of `to_vst`.
@@ -88,30 +84,24 @@ Note: As an alias, `bundle_model` can be used instead of `to_vst`.
 
 Loading a machine learning model from a .vst file is just as simple. Follow these steps:
 
-Import the necessary modules and functions:
-
-```python
-from verysimpletransformers import from_vst
-```
-
-Specify the path to the .vst file you want to load. Just like with `to_vst`,
-this path can be a `str`, `Path` or binary IO.
+Import `from_vst` from `simpletransformers`.
+Specify the path to the .vst file you want to load. Just like with `to_vst`, this path can be a `str`, `Path` or binary
+IO.
+Use the `from_vst` function to load the model. Optionally, you can specify the `device` parameter to set the device (
+e.g., 'cpu' or 'cuda'). If not specified, the function will select a device based on availability.
 
 Example:
 
 ```python
+from verysimpletransformers import from_vst
 from pathlib import Path
 
-fp = Path("model.vst")
-```
+fp = Path("model.vst")  # can also be simply a string.
 
-Use the `from_vst` function to load the model. Optionally, you can specify the `device` parameter to set the device (
-e.g., 'cpu' or 'cuda'). If not specified, the function will select a device based on availability.
+new_model = from_vst(fp,
+                     device='cuda',  # optional
+                     )
 
-Example:
-
-```python
-new_model = from_vst(fp, device='cuda')
 ```
 
 You can now use the `new_model` for various machine learning tasks.
@@ -126,6 +116,11 @@ Note: As an alias, `load_model` can be used instead of `to_vst`.
 - Ensure that you have the required dependencies, such as SimpleTransformers and PyTorch, installed to use these
   functions effectively.
 
+### Full Example
+
+To see a full example of saving and loading a `.vst` file,
+see [examples/basic.py](https://github.com/trialandsuccess/verysimpletransformers/tree/master/examples/basic.py)
+
 ## CLI
 
 The VerySimpleTransformers CLI provides a convenient and versatile way to interact with and manage your machine learning
@@ -173,6 +168,9 @@ vst serve ./classification.vst
 ./classification.vst serve 
 ```
 
+For more examples,
+see [examples/basic.sh](https://github.com/trialandsuccess/verysimpletransformers/tree/master/examples/basic.sh)
+
 ### Notes
 
 - A .vst file (e.g., 'model.vst') is required for most commands.

examples/basic.py

@@ -0,0 +1,71 @@
+from verysimpletransformers import from_vst, to_vst
+
+########################################
+### From the SimpleTransformers docs ###
+########################################
+
+from simpletransformers.classification import ClassificationModel, ClassificationArgs
+import pandas as pd
+import logging
+import torch
+
+logging.basicConfig(level=logging.INFO)
+transformers_logger = logging.getLogger("transformers")
+transformers_logger.setLevel(logging.WARNING)
+
+# Preparing train data
+train_data = [
+    ["Aragorn was the heir of Isildur", 1],
+    ["Frodo was the heir of Isildur", 0],
+]
+train_df = pd.DataFrame(train_data)
+train_df.columns = ["text", "labels"]
+
+# Preparing eval data
+eval_data = [
+    ["Theoden was the king of Rohan", 1],
+    ["Merry was the king of Rohan", 0],
+]
+eval_df = pd.DataFrame(eval_data)
+eval_df.columns = ["text", "labels"]
+
+# Optional model configuration
+model_args = ClassificationArgs(num_train_epochs=1)
+
+# Create a ClassificationModel
+model = ClassificationModel(
+    "roberta",
+    "roberta-base",
+    args=model_args,
+    use_cuda=torch.cuda.is_available()
+)
+
+# Train the model
+model.train_model(train_df)
+
+# Evaluate the model
+result, model_outputs, wrong_predictions = model.eval_model(eval_df)
+
+# Make predictions with the model
+predictions, raw_outputs = model.predict(["Sam was a Wizard"])
+
+print("Model Prediction:", predictions[0])
+
+######################################
+### Now let's package it into VST! ###
+######################################
+
+to_vst(model, "example_basic.vst", compression=5)
+
+# that's it!
+
+######################################
+### Now let's load the model again ###
+######################################
+
+model = from_vst("example_basic.vst")
+
+# that's it!
+predictions, _ = model.predict(["Sam was a Wizard"])
+
+print("New Model Prediction:", predictions[0])

examples/basic.sh

@@ -0,0 +1,7 @@
+python basic.py
+vst example_basic.vst
+vst run example_basic.vst
+vst serve example_basic.vst
+chmod +x example_basic.vst
+./example_basic.vst serve
+./example_basic.vst upgrade # warn: model is up-to-date