There are various libraries for time series forecasting in Python, and Darts is one of them. Unlike other forecasting libraries, Darts is a high-level forecasting library with algorithms to handle various time series data, regardless of the kind of trend they portray.

This tutorial will walk you through how you can forecast time series data using Python Darts. This will help you make meaningful insights whenever you come across time series data such as stock prices, weather measurements, and so on.

Here’s what we’ll cover:

• What is Python Darts?

• Prerequisites

• How to Set Up Dependencies

• Understanding the Dataset

• How to Prepare the Data for Darts

• How to Build a Forecasting Model

  • Classical Model

  • Machine Learning Models

  • How to Forecast with Deep Learning models

• Model Evaluation

• BackTesting

• Hyper Parameter Tuning

• Real-World Use Cases

• Best Practices

• Conclusion

What is Python Darts?

Python Darts is an open-source library for time series analysis and forecasting. It has various models ranging from statistical time series models like ARIMA, and SARIMA, to machine learning and deep learning models like Prophet, and LSTM.

It has various algorithms for handling missing imputations in time series data, and can handle time series problems ranging from univariate, multivariate to hierarchical time series.

Prerequisites

Before we proceed, you will need to have the following:

• Python 3.9+ installed.

• Jupyter Notebook, Google Colab, or Positron to run your code.

• Download the Netflix stock data.

• Have the following libraries installed:

  • darts for time series analysis

  • pandas for data wrangling

  • matplotlib for data visualization.

How to Set Up Dependencies

Load the following libraries.

import matplotlib.pyplot as plt
import pandas as pd
import darts
from darts import TimeSeries
from darts.models import ARIMA
from darts.models import RegressionModel
from lightgbm import LGBMRegressor
from darts.models import RNNModel
from darts.metrics import mape
import itertools

Understanding the Dataset

The Netflix stock data contains historical daily prices of Netflix stock from the year 2002 till date.

Load the data and have a preview of it.

netflix = pd.read_csv("/kaggle/input/netflix-stock-data-live-and-latest/Netflix_stock_history.csv")
netflix['Date'] = pd.to_datetime(netflix['Date'], utc=True).dt.tz_convert(None)
netflix.head()

To forecast a time series data, we need a Date column, which we already have, and then the variable of interest. We have several variables, but for this tutorial, we will focus on the Close variable of Netflix stocks.

Let’s visualize the data to see how Netflix closing price performed over the years.

netflix.plot(x='Date', y='Close', figsize=(10,5))
plt.show()

From the chart above, you can see that Netflix stock showed exponential growth in recent years. This means that the data is non-stationary, implying that there are no consistent changes over time.

There are a lot of random fluctuations in the data, which might make it difficult to forecast. Such data usually requires advanced models to handle the various fluctuations or noise present in the data.

How to Prepare the Data for Darts

Before preparing the data for Darts, you need to take note of few things.

First of all, if you look at our data preview earlier on, you would notice that it is recorded daily, we also need to fill in missing dates.

Copy and paste this code into your notebook.

start = netflix['Date'].min()
end = netflix['Date'].max()

netflix = (
    netflix.set_index('Date')
           .reindex(pd.date_range(start=start, end=end, freq='D'))
           .ffill()
           .reset_index()
           .rename(columns={'index': 'Date'})
)
netflix.head()

The code above ensures the netflix dataset has a continuous daily time series by filling in missing dates.

First, it finds the earliest start and latest end dates in the data, then creates a full daily date range between them.

By setting the Date column as the index and using .reindex() method, it inserts rows for any missing dates, which initially contain NaN.

The .ffill() method (forward fill) replaces these gaps by carrying forward the last known value, which is common for stock data when markets are closed, such as weekends.

Finally, the index is reset, and the column is renamed back to Date, producing a clean, continuous dataset ready for time series analysis.

Next, we need to convert the data to a Darts Timeseries object to make it usable by the Darts library.

 = TimeSeries.from_dataframe(
    netflix,
    time_col='Date',
    value_cols='Close',
)

The code above converts the netflix DataFrame into a Darts TimeSeries object, which is optimized for time series modeling and forecasting.

It takes the Date column (time_col='Date') as the timeline and the Close column (value_cols='Close') as the target values to forecast.

The resulting series object is now structured for use with Darts’ advanced forecasting models like ARIMA, Prophet, RNNs, and other time series algorithms.

Just like you would with any other machine learning model, you need to split your data into a training set and a validation set.

train, val = series.split_before(0.8)

How to Build a Forecasting Model

When building a forecasting model, you have the privilege of trying various models and picking the best-performing one.

The Darts library has various algorithms for time series analysis, from popular statistical algorithms like the Auto Regressive Integrated Moving Average (ARIMA) and Moving Average (MA) models, to machine learning and deep learning algorithms like Prophet and Long Short Term Memory (LSTM).

Note, I will only demonstrate how these algorithms work - it’s not necessary that we get accurate model metrics. But with further feature engineering, hyperparameter tuning, and cross-validation, you can get good results on your own.

Classical Model

The classical mode is the use of statistical time series models such as ARIMA. ARIMA is made up of the following components:

• AR (AutoRegressive): Predict past values by looking at previous ones.

• I (Integrated): Remove trends by focusing on changes instead of raw values.

• MA (Moving Average): Learn from the errors of past predictions to improve accuracy.

Run the code below in your notebook to fit an ARIMA model.

arima_model = ARIMA()
arima_model.fit(train)
arima_forecast = arima_model.predict(len(val))

To visualize the forecast by the model, call the .plot() method on the forecast object.

series.plot(label='actual')
arima_forecast.plot(label='forecast')
plt.legend()

You can improve the model by adding some additional parameters to the ARIMA() class. You can read more about that in the Darts documentation.

Machine Learning Models

Classical models like ARIMA can’t handle non-linear data. Machine learning models fill this gap. We’ll use the LightGBM model as an example.

The LightGBM is a machine learning model that builds models sequentially based on decision trees. It adds new decision trees that correct the errors of previous trees.

Although it was not designed to handle time series, with some feature engineering such as lags, rolling statistics, and seasonal indicators, you can make it learn patterns from time series data.

Run this code on your notebook to fit a LightGBM model on the Netflix data.

lgbm = LGBMRegressor()
lgbm_model = RegressionModel(lags=12, model=lgbm)
lgbm_model.fit(train)
lgbm_forecast = lgbm_model.predict(len(val))

From the code above, the lag argument is set to 12, which is the value of the Netflix stock price for 12 days before a selected day.

Let’s have a view of the forecast by running the following code.

series.plot(label='actual')
lgbm_forecast.plot(label='forecast')
plt.legend()

You can read more about tuning the LightGBM model from the Darts documentation to improve the above model.

How to Forecast with Deep Learning models

You can go for deep learning models designed for time series, such as LSTM, a kind of Recurrent Neural Network (RNN) designed to capture long-term dependencies in sequential data.

Run the following code to build the LSTM model.

lstm_model = RNNModel(model='LSTM', input_chunk_length=12, output_chunk_length=6, n_epochs=100)
lstm_model.fit(train)
lstm_forecast = rnn_model.predict(len(val))

Now let’s visualize the forecast and see what we have.

series.plot(label='actual')
lstm_forecast.plot(label='forecast')
plt.legend()

You can look up the Darts documentation to improve the model and check out other deep learning models also.

Model Evaluation

Now that you have three models, you need to select the best one among them using the Mean Absolute Percentage Error (MAPE).

It expresses the average absolute error as a percentage of the actual values, and the closer your value is to 0, the better your model.

Run the following to print the MAPE of each respective model.

arima_error = mape(val, arima_forecast)
print("MAPE:", arima_error)
lgbm_error = mape(val, lgbm_forecast)
print("MAPE:", lgbm_error)
lstm_error = mape(val, lstm_forecast)
print("MAPE:", lstm_error)

> MAPE: 38.33262525601514
> MAPE: 39.00241495209449
> MAPE: 38.82910057097827

The model with the lowest MAPE is the ARIMA model with approximately 38.33, which means it’s our best-performing model.

BackTesting

Darts has a feature called backtesting that allows you to evaluate your models based on historical data, using a rolling forecast.

Backtesting is like a time machine for forecasting. It simulates how your model would have performed in the past by repeatedly training it on historical data up to a certain point, making a prediction for the next step, then moving forward, and repeating the process.

This rolling evaluation simulates how the model would behave in real-world conditions, where future data is unknown, helping you measure its consistency and reliability over time, instead of just testing it once on a single validation set.

Since the ARIMA model is currently our best-performing model, run the code below to implement backtesting.

# Perform backtesting on the training + validation series
backtest_series = train.concatenate(val)

# Backtest
backtest_forecast = arima_model.historical_forecasts(
    series=backtest_series,
    start=0.8,          # fraction of the series to start forecasting from
    forecast_horizon=len(val),
    stride=1,           # step size of rolling forecast
    retrain=True,       # retrain the model at each step
    verbose=True
)

# Compute metrics
error = mape(backtest_series[-len(val):], backtest_forecast)
print(f"MAPE: {error:.2f}%")

> historical forecasts: 100%|██████████| 1/1 [00:02<00:00,  2.69s/it]MAPE: 47.27%

In the code above,

• The start argument defines where to start backtesting, which in this case is the last 20% series of the data.

• The forecast_horizon is how many steps ahead to forecast at each point.

• The stride is how frequently to retrain/forecast.

• The retrain=True refits the model at each step for realistic evaluation.

You can see that the MAPE, after backtesting, is higher because backtesting is more realistic, and it is more difficult to achieve a lower MAPE.

On your own, you can try to replicate backtesting for the other models.

Hyper Parameter Tuning

The ARIMA model has three hyperparameter:

• p which is the AR order

• d which is the differencing order

• q which is the MA order

You can use either grid or random search to tune your ARIMA model in Darts.

# Define possible values
p_values = range(0, 4)
d_values = range(0, 3)
q_values = range(0, 4)

best_mape = float('inf')
best_params = None

for p, d, q in itertools.product(p_values, d_values, q_values):
    try:
        arima_model = ARIMA(p=p, d=d, q=q)
        arima_model.fit(train)
        arima_forecast = arima_model.predict(len(val))
        arima_error = mape(val, arima_forecast)
        if arima_error < best_mape:
            best_mape = arima_error
            best_params = (p, d, q)
    except Exception as e:
        # Some combinations may fail
        continue

print(f"Best ARIMA params: p={best_params[0]}, d={best_params[1]}, q={best_params[2]} with MAPE={best_mape:.2f}%")

> Best ARIMA params: p=2, d=0, q=3 with MAPE=35.95%

In the above code, you define a range of possible values for the p, d , and q components, iterating over each combination of those values and choosing the model with the best MAPE among them.

Note that each model has its specific parameter you would have to tune, and you will need to check the Darts documentation for the hyperparameters of other models.

Real-World Use Cases

Forecasting time series data has a lot of real-world applications, some of which are:

• Stock price prediction: Like the dataset used in this tutorial, forecasting is used in finance for stock price prediction, allowing investors to manage risk.

• Demand forecasting for inventory: As a store owner, you can forecast product demands based on past sales of a product. This lets you know products that are in high demand.

• Energy consumption prediction: Governments, industries, and consumers can plan and manage energy production, distribution, and consumption efficiently, based on data from past usage. This helps to avoid blackouts and wastage, enabling them to prepare ahead.

Best Practices

• Always visualize residuals: Residuals are the difference between forecasted values and actual values. You must visualize them to detect outliers and unusual events.

• Perform proper backtesting: Backtesting lets you see a more realistic model, subjected to various changes that can occur in real life. When you backtest all your models, you end up getting a model that performs well when forecasting.

• Avoid data leakage: Do not train your models on validation sets to avoid bias, and always use cross-validation where necessary.

• Use domain knowledge for feature engineering: Ensure you understand the data you are working with. This comes in handy in feature engineering, when you want to come up with new features to help your forecasting model, especially in multivariate time series forecasting.

Conclusion

This tutorial is more like an overview, especially if you are new to time series, but you can build a lot just from what you have learned.

You already have an idea of what time series and forecasting are, and how you can use the Darts Python library to achieve that.

You also learned of various models for forecasting time series data, and how you can apply techniques such as backtesting and hyperparameter tuning to achieve better results.

Another interesting thing with Darts is its ability to handle hierarchical time series. Here, data is structured at aggregated levels.

Darts is one of the most powerful time series libraries in Python and has a lot of models to handle various cases. You can proceed to explore models such as Transformers and also multi-series forecasting, which are used for special use cases.

If you are interested in more data science and statistics articles, don’t forget to check out my blog.

YouTube Studio provides YouTube Analytics, where you can get comprehensive data about your channel. But there is a caveat: most of the statistics provided by YouTube Analytics are descriptive and not predictive. This means information like future views, subscriber counts, and factors influencing watch time or earnings are unavailable. This means you’ll need to calculate these metrics yourself.

In this article, you’ll learn how to export data from YouTube Analytics to Python so you can analyze it further or create visualizations. You can even build your own custom dashboard using various Python libraries like Streamlit, Shiny, or Dash.

Here’s what we

• Prerequisites

• Step 1: Identify the Problem Statement

• Step 2: Extract the Data

• Step 3: Analyze the Data in Python

  • Correlation Analysis

  • Audience Retention Analysis

• Conclusion

Prerequisites

• Active YouTube and YouTube Studio Account

• Jupyter Notebook, Google Colab, Kaggle, or any other environment that supports Python

• Pandas library installed

• Seaborn library installed

• Matplotlib library installed

Step 1: Identify the Problem Statement

Before proceeding, we need to know what we’re looking for – because YouTube Analytics has many metrics, and this can get overwhelming. My channel doesn’t have a ton of subscribers, but I have quite a few videos and views. So we’ll use my data as an example.

Just note that this analysis I’ll conduct in this tutorial is specific to my channel and can vary from channel to channel. You’ll be able to use the techniques here to answer the same/similar questions using your data, but your results will be different from mine.

Here are the questions I would like to find an answer for:

1. Correlation Analysis

• Views and watch time – Are longer watch times associated with higher views?

• Views and subscribers – Do more views translate to more subscribers?

• Impressions and Click-Through Rate (CTR%) – Does a stronger impression lead to better engagement?

• Watch time and average view duration – Are longer videos watched more?

2. Audience Retention Analysis

• Average view duration vs. Video length – Are longer videos watched in full?

• Drop-off points – Which duration range has the best retention?

• Retention Rate (%) – Watch time divided by duration?

Step 2: Extract the Data

Sign in to your YouTube Studio account, go to the Analytics tab, and click Advanced mode.

This will open a dashboard showing comprehensive descriptive analytics of your YouTube channel. This can get overwhelming, as there are a lot of metrics and filters with various types of data. This is why I emphasized the importance of knowing your problem and identifying your questions before diving in.

You can select the range of data you are interested in using the date dropdown (1 in the image below) and the Compare to button (2) to compare data from different date ranges.

The column headers you see in the dashboard are the filters. Each contains different metrics, and you can find some metrics in one or more filters. You can play around with the tabs and dropdowns to understand them better.

This is just a foundation for understanding your YouTube channel performance. If you have a long-running channel with a large number of subscribers and views, trust me – you can get a lot of insights from your data.

For this tutorial, I will select my entire lifetime data (1) and click the download button at the top right-hand corner (2).

This will display two options: whether to open the data in Google Sheets in a new tab or download the CSV file.

Since we want to use the data in Python, select the option to download the CSV file. After downloading the file, extract the files from the zip folder, and inside the extracted folder, you will see three CSV files: Chart data.csv, Table data.csv, and Totals.csv.

For this tutorial, we are interested in the Table data.csv. Click the data to open and view it in Excel to do some manual data cleaning before importing the data in Python.

The data is a list of all the videos on my YouTube channel, which is forty (yours might have more or fewer). Remove the first row, which is the Total row, and save the changes.

Here are the columns in the dataset:

• Content: The video id

• Video title: The video title

• Video publish time: The day the video was published

• Duration: The video duration in seconds

• Views: The number of views per video

• Watch time: The estimated amount of video watch time by your audience in hours

• Subscribers: Change in total subscribers found by subtracting subscribers lost from subscribers gained for the selected date and region.

• Average view duration: Estimated average minutes watched per video.

• Impressions: Number of times your videos were shown to viewers.

• Impressions click-through rate (%): Number of times viewers clicked your video after seeing an impression.

Step 3: Analyze the Data in Python

Go to your Jupyter Notebook and import the Pandas, Seaborn, and Matplotlib libraries.

import pandas as pd
import seaborn as sns
import matplotlib.pyplot as plt

Next, import the Table data.csv file.

# Load data
df = pd.read_csv("/content/Table data.csv")

Correlation Analysis

Concerning our problem statement, we are going to plot a correlation heatmap between the following variables: Views, Watch time (hours), Subscribers, Average view duration, and Impressions-click-through rate (%) to see the strength and direction of the relationship between them.

# Convert "Average view duration" (formatted as H:M:S) to seconds
df['Average view duration'] = pd.to_timedelta(df['Average view duration']).dt.total_seconds()

# Select relevant columns for correlation analysis
correlation_data = df[['Views', 'Watch time (hours)', 'Subscribers', 'Average view duration', 'Impressions', 'Impressions click-through rate (%)']]

# Compute correlation matrix
corr_matrix = correlation_data.corr()

# Visualization using a heatmap
plt.figure(figsize=(10, 6))
sns.heatmap(corr_matrix, annot=True, cmap='coolwarm', fmt=".2f", linewidths=0.5)
plt.title("YouTube Analytics Correlation Heatmap")
plt.show()

Correlation coefficient ranges from -1 to 1, where values less than 0 mean a negative relationship, while those above 0 mean a positive relationship. The lower the value in a negative relationship, the stronger the negative relationship, while the higher the value in a positive relationship, the stronger the relationship.

Based on the plot above, here are the key insights:

• Views and watch time: There's a strong correlation (0.94) between views and watch time, suggesting that as videos get more views, they also accumulate more watch hours, proportionally.

• Views and impressions: There's a strong correlation (0.89) between views and impressions, indicating that videos that are shown more frequently in recommendations and search results tend to get more views.

• Average view duration: This metric has very weak correlations with almost all other metrics. It is particularly notable in views (0.06), subscribers (0.01), and impressions (0.03).

• Subscribers and metrics: Subscribers have a moderate to strong correlation with views (0.75) and impressions (0.79) and a weaker correlation with click-through rate (0.54).

• Click-through rate: Has moderate correlations with views (0.69) and watch time (0.66) but a weaker correlation with subscribers (0.54).

The most significant insight is that average view duration appears to operate independently from other metrics. This suggests that on my YouTube channel, a video's ability to retain viewers throughout its length isn't necessarily connected to how many people watch it, how often it's recommended, or how many subscribers the channel has.

This implies that the strategies I would implement to increase my views, subscribers, and impressions might differ from those needed to improve average view duration, an important factor in YouTube's recommendation algorithm. This means I need to look at other YouTube metrics that have a relationship with average view duration, which is a topic for another article.

Audience Retention Analysis

To analyze audience retention, we need to create a new variable Retention Rate (%), which is calculated by dividing a video’s Average view duration by the Duration and expressing it as a percentage.

# Calculate retention rate as (Average View Duration / Total Video Duration) * 100
df['Retention Rate (%)'] = (df['Average view duration'] / df['Duration']) * 100

Next is to sort the videos in ascending order based on Retention Rate (%) and display the top 10 videos with the highest retention rate.

# Sort videos by retention rate
df_sorted = df.sort_values(by='Retention Rate (%)', ascending=False)

# Display top 10 videos with highest retention
df_sorted[['Video title', 'Duration', 'Average view duration', 'Retention Rate (%)']].head(10)

From the table above, you will notice that most of the videos in the top 10 spot are not above 503 seconds, which is approximately 8 minutes. This implies that my audience are interested in short, mid-range videos.

Most videos with the high retention rate have a duration less than 4 minutes, with a retention rate ranging from 27% - 40%. With this insight, I can ensure that the next videos I will upload are within 5 to 8 minutes.

Let’s take a look at the bottom 10 videos with a low retention rate:

# Sort videos by retention rate
df_sorted = df.sort_values(by='Retention Rate (%)', ascending=False)

# Display bottom 10 videos with highest retention
df_sorted[['Video title', 'Duration', 'Average view duration', 'Retention Rate (%)']].tail(10)

From the above information, you will notice that long videos in my channel spanning approximately 22 - 58 minutes have a low retention rate. This further supports the claim above that my audience is more interested in shorter videos.

We can further decide to plot a scattered plot of Duration against Retention Rate (%) to summarize the above tables.

# Set style for plots
sns.set_style("whitegrid")

# Plot Retention Rate vs. Video Duration
plt.figure(figsize=(12, 6))

sns.scatterplot(data=df, x='Duration', y='Retention Rate (%)', hue='Views', size='Views', sizes=(20, 200), palette='coolwarm')
plt.title("Audience Retention vs. Video Duration")
plt.xlabel("Video Duration (seconds)")
plt.ylabel("Retention Rate (%)")
plt.legend(title="Views", loc="upper right")

plt.show()

The scatter plot above shows the relationship between audience retention rate (y-axis, measured as a percentage) and video duration (x-axis, measured in seconds) for various videos. Here are the following key observations:

• There's a clear negative correlation between video duration and retention rate – as videos get longer, the retention rate generally decreases.

• The highest retention rates (35-40%) are found in shorter videos, mostly under 500 seconds (around 8 minutes).

• Videos over 1500 seconds (25 minutes) consistently show retention rates below 15%.

• The size and color of the dots represent the number of views, with larger, redder dots indicating more views (up to 1000) and smaller, blue dots representing fewer views (around 200).

• Interestingly, some mid-length videos (around 500 seconds) have both higher view counts (indicated by larger red dots) and decent retention rates of about 25%.

• The longest video in the dataset (at around 3500 seconds or 58 minutes) has a retention rate of about 14% and relatively few views.

This plot further confirms the claim that shorter videos tend to better maintain audience attention on my channel, though some mid-length videos can still perform well in terms of both retention and view count.

Conclusion

What we’ve learned from my data is just the tip of the iceberg. YouTube has many metrics, and because my channel is not monetized and has few subscribers and videos, I don’t have data on monetization, demographics, and other metrics.

But after reading this article, I hope that you can think of endless information you want to get based on these metrics. You can even forecast your views, subscriber counts, and revenue for the next days or months. You can also perform a multivariate time series analysis to see how these factors affect your primary variable of interest.

If you find this article interesting, don’t forget to check out my blog for other interesting articles, follow me on Medium, connect on LinkedIn, and subscribe to my YouTube channel.

In this tutorial, you will learn how to create such an API using the DeepSeek R1 large language model so external applications can call it. We will use the DeepSeek R1 model, available on HuggingFace, and the Plumber R package to deploy it as an API.

HuggingFace is an open source platform for building, training, and deploying machine learning models, while Plumber is an R package that expose R code as a RESTful APIs accessible to other applications through HTTP requests.

With this API, you can:

• Build AI applications

• Connect to external data and extract meaningful insights

• Integrate into existing applications to provide customer support, create documentations, and so on.

What is the DeepSeek R1 Model?

DeepSeek R1 is the latest large language model from the Chinese company DeepSeek. It was designed to enhance the problem-solving and analytic capabilities of AI systems.

DeepSeek-R1 uses reinforcement learning and supervised fine-tuning to handle complex reasoning tasks. Unlike proprietary models, DeepSeek R1 is open-source and free to use.

Prerequisites

• Sign up for a HuggingFace account if you don’t already have one

• Install R and R Studio.

• Install the plumber R package to build the API endpoint

• Install the httr2 R package to work with HTTP requests and interact with the Hugging Face API

Step 1: Create Your Project Repository

You need to create an R project to create an API application in R. This ensures that all the files needed to keep your API working are kept together under the same directory. R Studio already has a template provided for API projects, so you can follow the steps below to create yours.

In your R Studio IDE, click on the File menu and go to New Project to open the New Project Wizard. Once in the wizard, select New Directory, then click New Plumber API Project. Inside the directory name field, give it a name (for example DeepSeek-R1 API), and then click on Create Project.

You will see a file called plumber.R with a sample API template. This is where you’ll write the code to connect to the DeepSeek R1 model on HuggingFace. Make sure that you clear this template before proceeding.

Next, go to your terminal and create a .env file. This is where you will store the Hugging Face API key.

touch .env

Create a .gitignore file and add the .env file to it. This ensures that sensitive information like access tokens and API keys are not pushed to your Git repository.

Step 2: Create a Hugging Face Access Token

We need to create an access token to connect to Hugging Face models. Go to your profile, click Settings, and click Create New Token to create your access token for the Hugging Face repository.

Copy the access token and paste it into your .env file, and give it the name HUGGINGFACE_ACCESS_TOKEN.

HUGGINGFACE_ACCESS_TOKEN="<your-access-token>"

Next is to install the dotenv package, and paste the following code at the top of your plumber.R file:

# Load environment variables from .env
dotenv::load_dot_env()

dotenv::load_dot_env() loads all environment variables in the .env file, making them available to the plumber.R script.

Step 3: Build the DeepSeek API Endpoint

Now that we have our project environment set up and API token ready, we’ll write the code to build the API application by connecting to the DeepSeek R1 model on HuggingFace.

Go to the plumber.R file and load the following libraries:

library(plumber)
library(httr2)

Copy and paste the following code into plumber.R:

api_key <- Sys.getenv("HUGGINGFACE_ACCESS_TOKEN")



#* @post /deepseek_chat
function(prompt) {
  url <- "https://huggingface.co/api/inference-proxy/together/v1/chat/completions"

  # Create a request object
  req <- request(url) |>
    req_auth_bearer_token(api_key) |>
    req_body_json(list(
      model = "deepseek-ai/DeepSeek-R1",
      messages = list(
        list(role = "user", content = prompt)
      ),
      max_tokens = 500,
      stream = FALSE
    ))

  # Perform the request and capture the response
  res <- req_perform(req)

  # Parse the JSON response
  parsed_data <- res |>
    resp_body_json()

  # Extract the content from the response
  content <- parsed_data$choices
  return(content)
}

Here’s what’s going on in the above code:

• Sys.getenv gets the HuggingFace access token and stores it in the variable access_token.

• The url variable contains the API link to access the DeepSeek model on HuggingFace. You can get this by searching the model name deepseek-ai/DeepSeek-R1 on HuggingFace. Go to the View Code button, and under the cURL tab, copy the API URL

  

• #* @post /deepseek_chat means that the endpoint makes a POST request through the path /deepseek_chat.

• This endpoint takes an argument prompt, a text, or a question a user is expected to give.

• The req object is a chain of various operations, which makes a request() to the url, and then takes the api_key inside the req_auth_bearer_token() function. Model properties such as model name, role, prompt, and max_tokens are passed to the req object through the req_body_json function.

• The headers variable contains the authorization required to make a request to HuggingFace API.

• The request is performed and captured in a response object res using the req_perform() function.

• The res object returns a JSON object, which is now parsed to R using theresp_body_json() function.

• The content of the parsed_data is now returned so you can extract the information you need from the application for which you want to use the API.

Step 4: Test the API Endpoint

Let’s run the API endpoint to see how the application performs. Click on Run API. This will automatically open the API endpoint on your browser on the URL http://127.0.0.1:8634/docs/.

Click on the API endpoint dropdown, provide a prompt, and click the Execute button. You should receive a reply in a few minutes.

Conclusion

With your API, you can make inferences to the Hugging Face model and build AI applications in R or other programing languages. You need to host your API to make it accessible to clients online. There are various ways of hosting an R Plumber application: you can use Docker or host it on DigitalOcean using the plumberDeploy R package. However, the simplest and easiest way is to use Posit Connect.

You can use the same approach used in this tutorial to try out other HuggingFace models, build an API to generate images or translate different languages. R Plumber is easy to use, and the documentation provides many resources.

If you are interested in model deployment using R Plumber, you can check out this article on how to deploy a Time Series model built on Prophet using R Plumber.

If you find this article interesting, please check my other articles on learndata.xyz.

Compared to other front-end frameworks like React, Vue, or Angular, it focuses on a different approach by compiling components.

In most traditional frameworks, you build components using a virtual DOM (Document Object Model) abstraction.

In these frameworks, changes to the UI are first made to a virtual representation of the UI which calculates the differences and updates the actual DOM accordingly. This process can introduce overhead and performance bottlenecks, especially for complex applications.

Svelte, on the other hand, takes a different approach.

It shifts much of the work to the build process, compiling components into highly optimized JavaScript code that directly manipulates the DOM during runtime.

Svelte applications have a smaller runtime footprint and can often achieve better performance compared to applications built with traditional frameworks.

In this tutorial, you will learn how to build a simple calculator using Svelte.

Unlike most frameworks, Svelte does not have a steep learning curve. A basic understanding of HTML, CSS and JavaScript is sufficient to grasp Svelte.

The following are the prerequisites for this tutorial:

• Basic knowledge of HTML, CSS and JavaScript

• Willingness to learn

You can experience how the calculator works here.

How to Plan the Project

Those who fail to plan, plan to fail. It's a good practice to plan what you are building.

We want the calculator application to follow some criteria as follows:

• The calculator should have a user-friendly interface with buttons for digits (0-9), decimal point (.), and arithmetic operations (+, -, *, /).

• It should display the current input and the result on the screen.

• The calculator should support multiple arithmetic operations in sequence (for example: 2 + 3 * 5).

• The user should be able to clear the input and reset the calculator.

• The calculator should handle edge cases and prevent invalid inputs.

Below is a design of how the calculator should look like. You can use tools like Figma or Adobe XD to draw how you want your UI to look or sketch it on paper.

How to Build the User Interface

The calculator you will build is a simple app using Svelte REPL. It's an interactive coding environment that allows you to play with Svelte without going through the hassle of getting it set up locally on your PC.

But if you to prefer to follow locally, ensure you have Node.js installed, and run the following code on your terminal:

npm create svelte@latest <name-of-your-app>
cd myapp
npm install
npm run dev

You can read more here on how to get started.

Svelte allows you to build apps based on components written in a .svelte file. A web application contains components such as buttons, headers and so on.

Svelte simplifies this process by allowing you to create it once and reuse it in any part of your application. Most web applications contain one or more components.

The main application is in App.svelte, which contains the main code for the calculator app you are about to build.

When you open the Svelte REPL, you can see the default application prints Hello World on the screen:

<script>
    let name = 'world';
</script>

<h1>Hello {name}!</h1>

A .svelte file contains JavaScript, HTML and CSS.

The JavaScript, is written in the <script>...</script> tag, while you can write the HTML code below it, and apply CSS styling in the <style>...</style> tag.

<script>
    let name = 'world';
</script>

<h1>Hello {name}!</h1>
<style>
    h1{
        background: red;
    }
</style>

Variables declared in the script tag are displayed using the curly parentheses {}. Just like you can see Hello Word displayed using the name variable.

Now let's start building the application, copy and paste the following code into App.svelte:

<script>
</script>

<div class="calculator">
    <div class="display"></div>
    <div class="buttons">
        <button>7</button>
        <button>8</button>
        <button>9</button>
        <button class="operator">+</button>
        <button>4</button>
        <button>5</button>
        <button>6</button>
        <button class="operator">-</button>
        <button>1</button>
        <button>2</button>
        <button>3</button>
        <button class="operator">*</button>
        <button>0</button>
        <button>.</button>
        <button class="clear">C</button>
        <button class="operator">/</button>
        <button class="equals">=</button>
    </div>
</div>

<style>

</style>

If you have done that, you have created two divs – calculator and display. calculator is the parent div that contains display and the calculator buttons.

All arithmetic operations carry the class name operator. The clear sign also has the class name clear, and the equal sign has the class name equals.

You might not see the display now because we haven't applied CSS styling.

Inside the <style></style> tag, paste the code below:

<script>

</script>

...

<style>
.calculator {
    display: inline-block;
    border: 1px solid #ccc;
    padding: 10px;
    border-radius: 5px;
    box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
}

.display {
    font-size: 24px;
    border: 1px solid #ccc;
    height: 24px;
    padding: 10px;
    margin-bottom: 10px;
    width: 300px;
    text-align: right;
}
</style>

Now let's style the buttons into a grid of four columns.

Update the <style></style> tag with the buttons and button style below:

...

<style>
 ...
.buttons {
    display: grid;
    grid-template-columns: repeat(4, 75px);
    gap: 5px;
}

button {
    padding: 10px;
    font-size: 18px;
    border: none;
    cursor: pointer;
    border-radius: 5px;
    font-family: Arial, sans-serif;
    text-align: center;
}
</style>

Note that buttons is the class name for the div containing the various HTML button tags.

Next, let's style the buttons to improve user experience for anyone using the calculator and make the equal button occupy the empty spaces.

Update the <style></style> tag as follows:

...
<style>
 ...
 .operator{
    border: 0px solid #A46D19;
    background: #F90;
}
.clear{
    border: 0px solid #000;
    background: red;
}
.equals{
    border: 0px solid #000;
    background: #245BE9;
    width: 320px
}
</style>

Not done yet, one last thing to do.

You need to include hovering effect on all buttons, allowing a user to know when the mouse is on a particular button. This will make for a better user experience.

Update the <style></style> tag as follows:

...
<style>
    ...
.operator:hover{
    background: #FFD700;
}
.clear:hover {
    background: #FFC0CB ;
}
.equals:hover {
    background: #ADD8E6; 
}
</style>

Now we are done with the calculator's user interface.

If you did everything right, your code should look like this:

<script>
</script>

<div class="calculator">
    <div class="display"></div>
    <div class="buttons">
        <button>7</button>
        <button>8</button>
        <button>9</button>
        <button class="operator">+</button>
        <button>4</button>
        <button>5</button>
        <button>6</button>
        <button class="operator">-</button>
        <button>1</button>
        <button>2</button>
        <button>3</button>
        <button class="operator">*</button>
        <button>0</button>
        <button>.</button>
        <button class="clear">C</button>
        <button class="operator">/</button>
        <button class="equals">=</button>
    </div>
</div>

<style>
.calculator {
    display: inline-block;
    border: 1px solid #ccc;
    padding: 10px;
    border-radius: 5px;
    box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
}

.display {
    font-size: 24px;
    border: 1px solid #ccc;
    height: 24px;
    padding: 10px;
    margin-bottom: 10px;
    width: 300px;
    text-align: right;
}
.buttons {
    display: grid;
    grid-template-columns: repeat(4, 75px);
    gap: 5px;
}

button {
    padding: 10px;
    font-size: 18px;
    border: none;
    cursor: pointer;
    border-radius: 5px;
    font-family: Arial, sans-serif;
    text-align: center;
}
.operator{
    border: 0px solid #A46D19;
    background: #F90;
}
.clear{
    border: 0px solid #000;
    background: red;
}
.equals{
    border: 0px solid #000;
    background: #245BE9;
    width: 320px
}
.operator:hover{
    background: #FFD700;
}
.clear:hover {
    background: #FFC0CB ;
}
.equals:hover {
    background: #ADD8E6; 
}
</style>

Now let's start cooking!

How to Handle Interactivity

Now that you have finished with the UI, let's make the calculator interactive by starting with the number buttons.

Copy and paste the following code into the <script></script> tag in App.svelte:

<script>
    let display_number = "";
    const select = (num) => () => (display_number += num);
    const clear = () => (display_number = "");
</script>
...
...

• display_number is the number displayed on the calculator screen.

• select is the function that allows any number clicked, to appear on the screen.

• clear is the function that clears the screen, resetting the value of display number to an empty string.

Note that display_number is a string data type. Later on you will learn how to convert it to a numeric data type and perform calculations with it.

Next let's implement the select and clear function into the HTML.

Modify the HTML as follows:

...
<div class="calculator">
    <div class="display">{display_number}</div>
        <div class="buttons">
            <button on:click={select(7)}>7</button>
            <button on:click={select(8)}>8</button>
            <button on:click={select(9)}>9</button>
            <button class="operator" >+</button>
            <button on:click={select(4)}>4</button>
            <button on:click={select(5)}>5</button>
            <button on:click={select(6)}>6</button>
            <button class="operator" >-</button>
            <button on:click={select(1)}>1</button>
            <button on:click={select(2)}>2</button>
            <button on:click={select(3)}>3</button>
            <button class="operator">*</button>
            <button on:click={select(0)}>0</button>
            <button on:click={select(".")}>.</button>
            <button on:click={clear} class="clear">C</button>
            <button class="operator">/</button>
            <button class="equals" >=</button>
        </div>
</div>

...

Svelte on:click directive allows you attach an event handler to an element, so that when you call the select function for an element, it displays the number of that element appended to the previous value.

The clear button also has the event handler clear, to clear the screen and reset to "" anytime it's called.

If you get everything right, you should see the value of the buttons clicked on the screen.

Let's create an event handler to perform an addition function and display the result. This will serve as the basis for all other operations in the calculator.

Update the <script></script> tag as follows:

<script>
    ...
    let operand;
    let result;

    function addition() {
        operand = Number(display_number);
        display_number = "";
    }

    function equals() {
        display_number = Number(display_number);
        result = operand + display_number
        display_number = result.toString()
    }
</script>
...
...

When performing calculations, you can have two or more operands – operand is the variable where the previous operand is stored, while display_number contains the current operand.

result is the final result after performing an arithmetic operation.

The addition function takes the initial value displayed, converts it to a Number and stores it in the new variable operand, which resets display_number to its initial value "".

The equals function takes the new currently displayed number, adds it to operand and saves it as the final result. result is now converted to a string and saved as display_number so it appears on the screen.

Note that the equals function converts result to a string. When you want to use it for another calculation, the addition function will handle the conversion to a Number.

Try performing an addition operation to see if you got it right.

By now, App.svelte should look like this:

<script>
    let display_number = "";
    const select = (num) => () => (display_number += num);
    const clear = () => (display_number = "");

    let operand;
    let result;

    function addition() {
            operand = Number(display_number);
            display_number = "";
      }

    function equals() {
            display_number = Number(display_number);
            result = operand + display_number
            display_number = result.toString()
      }
</script>

<div class="calculator">
    <div class="display">{display_number}</div>
        <div class="buttons">
            <button on:click={select(7)}>7</button>
            <button on:click={select(8)}>8</button>
            <button on:click={select(9)}>9</button>
            <button on:click={addition} class="operator" >+</button>
            <button on:click={select(4)}>4</button>
            <button on:click={select(5)}>5</button>
            <button on:click={select(6)}>6</button>
            <button class="operator" >-</button>
            <button on:click={select(1)}>1</button>
            <button on:click={select(2)}>2</button>
            <button on:click={select(3)}>3</button>
            <button class="operator">*</button>
            <button on:click={select(0)}>0</button>
            <button on:click={select(".")}>.</button>
            <button on:click={clear} class="clear">C</button>
            <button class="operator">/</button>
            <button on:click={equals} class="equals" >=</button>
        </div>
</div>

<style>
.calculator {
    display: inline-block;
    border: 1px solid #ccc;
    padding: 10px;
    border-radius: 5px;
    box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
}

.display {
    font-size: 24px;
    border: 1px solid #ccc;
    height: 24px;
    padding: 10px;
    margin-bottom: 10px;
    width: 300px;
    text-align: right;
}
.buttons {
    display: grid;
    grid-template-columns: repeat(4, 75px);
    gap: 5px;
}

button {
    padding: 10px;
    font-size: 18px;
    border: none;
    cursor: pointer;
    border-radius: 5px;
    font-family: Arial, sans-serif;
    text-align: center;
}
.operator{
    border: 0px solid #A46D19;
    background: #F90;
}
.clear{
    border: 0px solid #000;
    background: red;
}
.equals{
    border: 0px solid #000;
    background: #245BE9;
    width: 320px
}
.operator:hover{
    background: #FFD700;
}
.clear:hover {
    background: #FFC0CB ;
}
.equals:hover {
    background: #ADD8E6; 
}
</style>

Let's improve the code to support other operations – subtraction, multiplication and division:

<script>
...
let operator;
let operators = ["+", "-", "*", "/"];

function operation(sign) {
        operand = Number(display_number);
        operator = sign;
        display_number = "";
  }

function equals() {
    display_number = Number(display_number);
    if (operator === "+") {
      result = operand + display_number;
    } else if (operator === "-") {
      result = operand - display_number;
    } else if (operator === "*") {
      result = operand * display_number;
    } else if (operator === "/") {
      result = operand / display_number;
    }
display_number = result.toString()
</script>
...
...

The addition function changes to operation, which supports the sign argument.

The equals function performs operations based on the value of the sign argument in the function operation.

Update the HTML code to add event handlers to the various arithmetic operations:

<div class="calculator">
    <div class="display">{display_number}</div>
        <div class="buttons">
            <button on:click={select(7)}>7</button>
            <button on:click={select(8)}>8</button>
            <button on:click={select(9)}>9</button>
            <button on:click={() => operation(operators[0])} class="operator" >+</button>
            <button on:click={select(4)}>4</button>
            <button on:click={select(5)}>5</button>
            <button on:click={select(6)}>6</button>
            <button on:click={() => operation(operators[1])} class="operator" >-</button>
            <button on:click={select(1)}>1</button>
            <button on:click={select(2)}>2</button>
            <button on:click={select(3)}>3</button>
            <button on:click={() => operation(operators[2])} class="operator">*</button>
            <button on:click={select(0)}>0</button>
            <button on:click={select(".")}>.</button>
            <button on:click={clear} class="clear">C</button>
            <button on:click={() => operation(operators[3])} class="operator">/</button>
            <button on:click={equals} class="equals" >=</button>
        </div>
</div>

Each function takes its sign value by accessing the respective sign in operators.

We now have a working calculator.

Now, how do we handle something like this?

The above is a bug where the numbers exceed the display boundaries.

To solve this error, update the display div as follows:

...
<div class="calculator">
    <div class="display">{display_number.length < 23? display_number: display_number.substring(0,23)}</div>
    ...
</div>
...

If the length of display_number is greater than 22, which is the number of digits the display screen can contain, the first twenty-two characters is selected.

This will fix the above bug.

Challenge

You can further extend the calculator by:

• Adding advanced mathematical and scientific operations.

• Giving room for users to use their keyboard to input values.

• Displaying the arithmetic operations on screen, before calculating.

Conclusion

In this tutorial, you have learned how to use Svelte to create interactivity in a web app. And you also learned about Svelte event handlers.

You can further your current Svelte knowledge by visiting the official documentation.

Well, how about building a WhatsApp bot that can give you the meaning of words you want to know?

In this tutorial, you will learn how to build a chatbot that can serve as your dictionary. It'll be easily accessible on WhatsApp using the Twilio MessagingX WhatsApp API to send and receive messages. We'll use Fast API to create the web server and interact with the database, and MongoDB to store the words and their meanings into a database.

By the end of this tutorial, you will have developed a functional chatbot that can define words in real-time while you're conversing on WhatsApp.

Prerequisites

• Python 3.9+ installed on your machine.

• MongoDB free account – if you don’t have one, you can set it up here.

• Twilio free account – you can set up one here.

• Merriam-Webster Developer’s account – you can set up one here.

• An IDE or text editor, such as VS code.

Set Up Your Development Environment

Before you start, you need to set up your development environment by creating the required directory and files. Here's the commands for that:

mkdir whatsappDictionary
cd whatsappDictionary
touch requirements.txt models.py utils.py main.py .env

• requirements.txt contains the required libraries to get the chatbot up and running.

• model.py contains the code connecting your chatbot to the MongoDB server

• utils.py includes the code to connect to Twilio MessagingX WhatsApp API

• main.py contains the code to build the Fast API server and connect to the Merriam-Webster API.

• whatsappDictionary is the directory for all the files.

Next, you'll create and activate a virtual environment and update the Python package manager pip to the most recent version using the following command:

python -m venv venv; ./venv/Scripts/Activate; pip --upgrade pip

If you are on a Linux machine, use this command:

pyton -m venv venv; venv\\Scripts\\activate.bat; pip --upgrade pip

To learn more about virtual environments and their benefits, you can read this tutorial.

Next you'll need to populate the requirements.txt file with the following dependencies:

fastapi
uvicorn
twilio
pymongo
pyngrok
requests
dotenv

• fastapi is a Python framework for building APIs quickly and easily

• uvicorn is a lightning-fast server implementation for Python

• twilio allows you to interact with the Twilio MessagingX WhatsApp API

• pymongo is the driver you will use to connect to the MongoDB server

• pyngrok enables you to tunnel a local server to a public URL

• requests allow you to send HTTP requests using Python

• dotenv loads the environment variables from the .env file.

Install these dependencies by running the following command on your terminal:

pip install -r requirements.txt

Configure the Database

You now want to set up a database to store words and their definitions. You are going to use MongoDB, which is a NoSQL language and is easy to set up.

You will need to create a free account on the MongoDB website (if you don't have one already). Once you have an account, log in to create a new Shared cluster and database.

Image showing how to create a shared cluster on Mongo DB

Afterwards, go to Security_,_ then ADD NEW DATABASE USER to add a new user with read/write access to the database.

This image shows the tab where you can add a new database

This image shows the window of adding a new database user

Go back to the cluster dashboard, click on Connect and then on Drivers.

This image shows you the final process while trying to connect to the cluster

Copy the code shown to you into model.py:

This image shows the code on how to connect to the MongoDB server using the pymongo driver.

from pymongo.mongo_client import MongoClient
from pymongo.server_api import ServerApi

uri = f"mongodb+srv://adejumoridwan:<password>@cluster0.d9jr4ev.mongodb.net/?retryWrites=true&w=majority"

# Send a ping to confirm a successful connection
try:
    client.admin.command('ping')
    print("Pinged your deployment. You successfully connected to MongoDB!")
except Exception as e:
    print(e)

Give your password to run the code and connect to the MongoDB server. You don’t want anyone to see this. Go to the .env file you created and store your password there.

MONGO_SECRET=<password>

Next, update model.py to access the .env file.

from pymongo.mongo_client import MongoClient
from pymongo.server_api import ServerApi
from dotenv import load_dotenv
import os

load_dotenv()
password = os.environ.get('MONGO_SECRET')

uri = f"mongodb+srv://adejumoridwan:{password}@cluster0.d9jr4ev.mongodb.net/?retryWrites=true&w=majority"

# Send a ping to confirm a successful connection
try:
    client.admin.command('ping')
    print("Pinged your deployment. You successfully connected to MongoDB!")
except Exception as e:
    print(e)

• load_dotenv() loads the variables in .env

• os.environ.get('MONGO_SECRET') receives the password from .env, which stores the variable password

Run the script to connect to the MongoDB server. You can create a collection by clicking on your Cluster name and going to Collections. Collections are NoSQL versions of SQL tables.

Click on Create Database to create your database:

This shows information and tabs regarding the created clusters such as Overview, Collections and so on

Give the database and collection names. The database and collection names for this tutorial are MY_DB and dictionary, respectively.

The window shows you the option to fill in when you want to create a database, such as a database name, collection name, and additional preferences.

Go to models.py and update the code to create a new client and connect to the server.

from pymongo.mongo_client import MongoClient
from pymongo.server_api import ServerApi
from dotenv import load_dotenv
import os

load_dotenv()
password = os.environ.get('MONGO_SECRET')

uri = f"mongodb+srv://adejumoridwan:{password}@cluster0.d9jr4ev.mongodb.net/?retryWrites=true&w=majority"

# Create a new client and connect to the server
client = MongoClient(uri, server_api=ServerApi('1'))

dictionary_collection = client["MY_DB"]["dictionary"]

# Send a ping to confirm a successful connection
try:
    client.admin.command('ping')
    print("Pinged your deployment. You successfully connected to MongoDB!")
except Exception as e:
    print(e)

dictionary_collection is what you will use to update entries into the server later.

How to Configure Twilio Sandbox for WhatsApp

To configure the Twilio sandbox for WhatsApp, go to Twilio Console. Under Develop, click on Messaging, then Try it out. Under Try it out, click on Send a WhatsApp Message.

This sandbox allows you to send WhatsApp messages to your number

To connect to the WhatsApp Sandbox, save the number provided on the sandbox on your device and send the message join manner-free to the number, or you can scan the QR code on your device.

Here you see the sandbox to connect to whatsapp sandbox to your number

Once the connection is successful, copy the code and paste it into the file utils.py:

Here you can see how to connect to WhatsApp API in various languages. Currently, the image is showing how to connect to WhatsApp API so that you can send messages from Twilio.

from twilio.rest import Client

account_sid = '<account_sid>'
auth_token = '[AuthToken]'
client = Client(account_sid, auth_token)

message = client.messages.create(
  from_='whatsapp:+14155238886',
  body='Your appointment is coming up on July 21 at 3PM',
  to='whatsapp:<to_number>
)

print(message.sid)

The client.messages.create() function allows you to send messages to your WhatsApp from the WhatsApp sandbox. It takes three parameters:

• from_ is where the message is coming from, that is, from the WhatsApp Sandbox

• body takes in the body of your message

• to is the WhatsApp number you are sending to

How to Connect to the Twilio API

Go to the .env file to store your Twilio authentication token, account SID, Twilio sandbox number, and WhatsApp number.

MONGO_SECRET="<password>"
TWILIO_ACCOUNT_SID="<account_sid>"
TWILIO_AUTH_TOKEN="<auth_token>"
TWILIO_NUMBER="<twilio_number>"
TO_NUMBER="<to_number>"

Update the utils.py file to access these variables:

from twilio.rest import Client
from dotenv import load_dotenv
import os

load_dotenv()

account_sid = os.getenv("TWILIO_ACCOUNT_SID")
auth_token = os.getenv("TWILIO_AUTH_TOKEN")
client = Client(account_sid, auth_token)
twilio_number = os.getenv('TWILIO_NUMBER')
to_number = os.getenv(“TO_NUMBER”)

message = client.messages.create(
  from_=f'whatsapp:{twilio_number}',
  body='Your appointment is coming up on July 21 at 3PM',
  to=f'whatsapp:{to_number}
)

load_dotenv() loads the environment variables, and os.getenv gets these variables from the environment.

Next is to define a send_message function. This function is going to have two arguments: to_number and text. The function will send a message defined in text to to_number.

from twilio.rest import Client
from dotenv import load_dotenv
import os

load_dotenv()

account_sid = os.getenv("TWILIO_ACCOUNT_SID")
auth_token = os.getenv("TWILIO_AUTH_TOKEN")
client = Client(account_sid, auth_token)
twilio_number = os.getenv('TWILIO_NUMBER')

def send_message(to_number, text):
      message = client.messages.create(
          from_=f"whatsapp:{twilio_number}",
          body=text,
          to=f"whatsapp:{to_number}"
          )

Update the send_message function to configure logging in case errors are encountered when sending messages.

import logging
from dotenv import load_dotenv
import os
from twilio.rest import Client

load_dotenv()

account_sid = os.getenv("TWILIO_ACCOUNT_SID")
auth_token = os.getenv("TWILIO_AUTH_TOKEN")
client = Client(account_sid, auth_token)
twilio_number = os.getenv('TWILIO_NUMBER')

# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Sending message logic through Twilio Messaging API
def send_message(to_number, text):
    try:
        message = client.messages.create(
            from_=f"whatsapp:{twilio_number}",
            body=text,
            to=f"whatsapp:{to_number}"
            )
        logger.info(f"Message sent to {to_number}: {message.body}")
    except Exception as e:
        logger.error(f"Error sending message to {to_number}: {e}")

How to Build the FastAPI Backend

Inside the main.py, set up a basic FastAPI application.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def index():
    return {"message": "I love FreeCodeCamp"}

The code below sets up a basic FastAPI backend, creating a new instance of the FastAPI class and assigning it to the app variable.

The @app.get decorator creates a new endpoint that you can access with an HTTP GET request. The endpoint is at the root URL / and returns a JSON response with a single key-value pair: "message": "I love FreeCodeCamp".

To run the app, run the following command in your terminal:

uvicorn main:app --reload

On your browser, open the host http://127.0.0.1:8000. You will see a JSON response of {"message": "I love FreeCodeCamp"}. You can also access an interactive API doc provided by swagger on the host http://127.0.0.1:8000/doc which allows you to interact with your API and see if you have any errors.

This interactive documentation provided by swagger shows how to interact with your API to check for errors.

How to Set Up ngrok

To receive Twilio messages on the backend, you will use ngrok to host the local host on a public server. Read this post to learn how to set up ngrok on your machine.

On ngrok administrator, run the command ngrok http 8000. This makes your host public, and you can receive messages on your backend.

Here you can see ngrok up and running on your local machine

Go to your WhatsApp Sandbox, under Sandbox settings, and paste the forwarding URL https://b5a6-105-112-120-51.ngrok-free.app appending it with /message under When a message comes in and click Save.

This image shows how to configure your sandbox and link to the ngrok url

How to Connect to the Merriam-Webster API

To set up a Merriam-Webster dictionary account, go here and fill out your credentials:

Image showing page to register for Merriam Webster Developer Center

You can register for two keys: Collegiate Dictionary and Collegiate Thesaurus, though this tutorial uses only Collegiate Dictionary.

This shows the various keys one can apply for on Merriam-Webster

After filling in all your details, click on Register and Login.

In the home tab, go to Keys to get your API keys.

This key tab shows the keys you have registered for

Update the .env file, saving the key as DICTIONARY_KEY.

MONGO_SECRET="<password>"
TWILIO_ACCOUNT_SID="<account_sid>"
TWILIO_AUTH_TOKEN="<auth_token>"
TWILIO_NUMBER="<twilio_number>"
TO_NUMBER="<to_number>"
DICTIONARY_API_KEY="<dictionary_key>"

Update the main.py as follows:

from fastapi import FastAPI, Form
import requests
from utils import send_message
from dotenv import load_dotenv
import os
from typing import List

load_dotenv()

app = FastAPI()
whatsapp_number = os.getenv("TO_NUMBER")
api_key = os.getenv("DICTIONARY_API_KEY")

@app.post("/message")
async def reply(Body: str = Form()):
    url = f"<https://www.dictionaryapi.com/api/v3/references/collegiate/json/{Body}?key={api_key}>"
    response = requests.get(url)
    # Extract the JSON data from the response
    data = response.json()

    definition = data[0]["shortdef"][0]

    send_message(whatsapp_number, definition)

@app.post("/message") is a decorator in the fastAPI framework that defines a POST request route to the URL /message. The reply function defined above is called when a POST request is sent to this URL.

The reply function takes in a Body parameter in the request body, which is the message sent to the chatbot (the word you want to get the definition of). It then sends an HTTP request to the Merriam-Webster API to retrieve the word's meaning.

The url variable stores the link to Merriam-Webster API, which takes the Body and the api_key to get details regarding the provided word.

You can make requests from url using requests from the request library and storing request.get(url) into the response variable.

You then extract the JSON data from the response using response.json() and store it in variable data.

data[0]["shortdef"][0] allows you to access the short definition of a word stored in the variable definition.

send_message() takes the definition and sends it to whatsapp_number.

Next, you'll need to handle situations where someone sends a sentence instead of a word, or a word containing punctuations or characters. So update main.py as follows:

from fastapi import FastAPI, Form
import requests
from utils import send_message
from dotenv import load_dotenv
import os
from typing import List
from models import dictionary_collection

load_dotenv()

app = FastAPI()
whatsapp_number = os.getenv("TO_NUMBER")
api_key = os.getenv("DICTIONARY_API_KEY")

@app.post("/message")
async def reply(Body: str = Form()):
    url = f"<https://www.dictionaryapi.com/api/v3/references/collegiate/json/{Body}?key={api_key}>"
    flag="Please give a valid word"

    if Body.isalpha():
        response = requests.get(url)
        # Extract the JSON data from the response
        data = response.json()

        definition = data[0]["shortdef"][0]

        send_message(whatsapp_number, definition)
    else:
        return send_message(whatsapp_number, flag)

    return ""

flag is a variable storing the message to give if you provide a sentence or a word with characters.

The if condition checks if a message is a word through Body.isaplha(), if true it gets the definition from Merriam-Webster API if false it returns the function send_message() telling the user to Please give a valid word.

To store the words and their meanings to the MongoDB database, update main.py as follows:

from fastapi import FastAPI, Form
import requests
from utils import send_message
from dotenv import load_dotenv
import os
from typing import List
from models import dictionary_collection

load_dotenv()

app = FastAPI()
whatsapp_number = os.getenv("TO_NUMBER")
api_key = os.getenv("DICTIONARY_API_KEY")

@app.post("/message")
async def reply(Body: str = Form()):
    url = f"<https://www.dictionaryapi.com/api/v3/references/collegiate/json/{Body}?key={api_key}>"
    flag="Please give a valid word"

    if Body.isalpha():
        response = requests.get(url)
        # Extract the JSON data from the response
        data = response.json()

        definition = data[0]["shortdef"][0]

        send_message(whatsapp_number, definition)

        dictionary_db = {"word":Body, "definition":definition}
        dictionary_collection.insert_one(dictionary_db)

    else:
        return send_message(whatsapp_number, flag)

    return ""

dictionary_db = {"word": Body, "definition": definition} creates a dictionary with two keys, word and definition, and values Body and definition, respectively.

dictionary_collection.insert_one(dictionary_db) inserts the dictionary into the MongoDB collection, named dictionary_collection.

You can go to your dashboard and view the items added to the collection.

This contains the items that have been sent and received on your application

Test the ChatBot

Now you can chat with the chatbot and ask for definitions of words:

Image showing a chat with the dictionary chatbot

Conclusion

In this tutorial, you learned how to create a WhatsApp dictionary chatbot. You learned how to use FastAPI to power the backend of your application, how to interact with Twilio MessagingX WhatsApp API, and how to use NoSQL database like MongoDB to store your data.

You can extend the chatbot to get synonyms and definitions of words with more than one explanation by accessing more metadata from the Merriam-Webster API.

You can check out the Merriam-Webster API documentation for the various responses you can get. Ensure you read the Twilio WhatsApp API docs for more advanced functionalities like getting media replies and word pronunciation.