Add feast example (#19)

* edit readme

* move flight example into separate folder

* add new feast example

* edit gitignore

* add imgs

* minor edits

* edit why page

* fix branch name

* edit home page

* add new tutorial

* remove separate data model page

* minor change

Author: zseta

.gitignore

@@ -1,2 +1,5 @@
 /docs/_build
-/source/.doctrees
+/source/.doctrees
+feature_repo/data/registry.db
+/encoder.bin
+/model.bin

app.py

@@ -0,0 +1,117 @@
+import datetime
+from collections import OrderedDict
+
+import numpy as np
+import pandas as pd
+import shap
+import streamlit as st
+from matplotlib import pyplot as plt
+
+from credit_model import CreditScoringModel
+
+st.set_page_config(layout="wide")
+model = CreditScoringModel()
+if not model.is_model_trained():
+    raise Exception("The credit scoring model has not been trained. Please run `python run.py`.")
+
+
+def get_loan_request():
+    zipcode = st.sidebar.text_input("Zip code", "94109")
+    date_of_birth = st.sidebar.date_input(
+        "Date of birth", value=datetime.date(year=1986, day=19, month=3)
+    )
+    ssn_last_four = st.sidebar.text_input(
+        "Last four digits of social security number", "3643"
+    )
+    dob_ssn = f"{date_of_birth.strftime('%Y%m%d')}_{str(ssn_last_four)}"
+    age = st.sidebar.slider("Age", 0, 130, 25)
+    income = st.sidebar.slider("Yearly Income", 0, 1000000, 120000)
+    person_home_ownership = st.sidebar.selectbox(
+        "Do you own or rent your home?", ("RENT", "MORTGAGE", "OWN")
+    )
+
+    employment = st.sidebar.slider(
+        "How long have you been employed (months)?", 0, 120, 12
+    )
+
+    loan_intent = st.sidebar.selectbox(
+        "Why do you want to apply for a loan?",
+        (
+            "PERSONAL",
+            "VENTURE",
+            "HOMEIMPROVEMENT",
+            "EDUCATION",
+            "MEDICAL",
+            "DEBTCONSOLIDATION",
+        ),
+    )
+
+    amount = st.sidebar.slider("Loan amount", 0, 100000, 10000)
+    interest = st.sidebar.slider("Preferred interest rate", 1.0, 25.0, 12.0, step=0.1)
+    return OrderedDict(
+        {
+            "zipcode": [int(zipcode)],
+            "dob_ssn": [dob_ssn],
+            "person_age": [age],
+            "person_income": [income],
+            "person_home_ownership": [person_home_ownership],
+            "person_emp_length": [float(employment)],
+            "loan_intent": [loan_intent],
+            "loan_amnt": [amount],
+            "loan_int_rate": [interest],
+        }
+    )
+
+
+# Application
+st.title("Loan Application")
+
+# Input Side Bar
+st.header("User input:")
+loan_request = get_loan_request()
+df = pd.DataFrame.from_dict(loan_request)
+df
+
+# Full feature vector
+st.header("Feature vector (user input + zipcode features + user features):")
+vector = model._get_online_features_from_feast(loan_request)
+ordered_vector = loan_request.copy()
+key_list = vector.keys()
+key_list = sorted(key_list)
+for vector_key in key_list:
+    if vector_key not in ordered_vector:
+        ordered_vector[vector_key] = vector[vector_key]
+df = pd.DataFrame.from_dict(ordered_vector)
+df
+
+# Results of prediction
+st.header("Model prediction:")
+result = model.predict(loan_request)
+
+if result == 0:
+    st.success("Your loan has been approved!")
+elif result == 1:
+    st.error("Your loan has been rejected!")
+
+
+# Feature importance - todo
+    """
+st.header("Feature Importance")
+X = pd.read_parquet("feature_repo/data/training_dataset_sample.parquet")
+explainer = shap.TreeExplainer(model.classifier)
+shap_values = explainer.shap_values(X)
+left, mid, right = st.columns(3)
+with left:
+    plt.title("Feature importance based on SHAP values")
+    print(X.shape)
+    print(shap_values[3].shape)
+    shap.summary_plot(shap_values[1], X)
+    st.set_option("deprecation.showPyplotGlobalUse", False)
+    st.pyplot(bbox_inches="tight")
+    st.write("---")
+
+with mid:
+    plt.title("Feature importance based on SHAP values (Bar)")
+    shap.summary_plot(shap_values, X, plot_type="bar")
+    st.pyplot(bbox_inches="tight")
+    """

credit_model.py

@@ -0,0 +1,132 @@
+from pathlib import Path
+
+import feast
+import joblib
+import pandas as pd
+from sklearn import tree
+from sklearn.exceptions import NotFittedError
+from sklearn.preprocessing import OrdinalEncoder
+from sklearn.utils.validation import check_is_fitted
+
+
+class CreditScoringModel:
+    categorical_features = [
+        "person_home_ownership",
+        "loan_intent",
+        "city",
+        "state",
+        "location_type",
+    ]
+
+    feast_features = [
+        "zipcode_features:city",
+        "zipcode_features:state",
+        "zipcode_features:location_type",
+        "zipcode_features:tax_returns_filed",
+        "zipcode_features:population",
+        "zipcode_features:total_wages",
+        "credit_history:credit_card_due",
+        "credit_history:mortgage_due",
+        "credit_history:student_loan_due",
+        "credit_history:vehicle_loan_due",
+        "credit_history:hard_pulls",
+        "credit_history:missed_payments_2y",
+        "credit_history:missed_payments_1y",
+        "credit_history:missed_payments_6m",
+        "credit_history:bankruptcies",
+    ]
+
+    target = "loan_status"
+    model_filename = "model.bin"
+    encoder_filename = "encoder.bin"
+
+    def __init__(self):
+        # Load model
+        if Path(self.model_filename).exists():
+            self.classifier = joblib.load(self.model_filename)
+        else:
+            self.classifier = tree.DecisionTreeClassifier()
+
+        # Load ordinal encoder
+        if Path(self.encoder_filename).exists():
+            self.encoder = joblib.load(self.encoder_filename)
+        else:
+            self.encoder = OrdinalEncoder()
+
+        # Set up feature store
+        self.fs = feast.FeatureStore(repo_path="feature_repo")
+
+    def train(self, loans):
+        train_X, train_Y = self._get_training_features(loans)
+
+        self.classifier.fit(train_X[sorted(train_X)], train_Y)
+        joblib.dump(self.classifier, self.model_filename)
+
+    def _get_training_features(self, loans):
+        training_df = self.fs.get_historical_features(
+            entity_df=loans, features=self.feast_features
+        ).to_df()
+
+        self._fit_ordinal_encoder(training_df)
+        self._apply_ordinal_encoding(training_df)
+        train_X = training_df[
+            training_df.columns.drop(self.target)
+            .drop("event_timestamp")
+            .drop("created_timestamp__")
+            .drop("loan_id")
+            .drop("zipcode")
+            .drop("dob_ssn")
+        ]
+        train_X = train_X.reindex(sorted(train_X.columns), axis=1)
+        train_Y = training_df.loc[:, self.target]
+
+        return train_X, train_Y
+
+    def _fit_ordinal_encoder(self, requests):
+        self.encoder.fit(requests[self.categorical_features])
+        joblib.dump(self.encoder, self.encoder_filename)
+
+    def _apply_ordinal_encoding(self, requests):
+        requests[self.categorical_features] = self.encoder.transform(
+            requests[self.categorical_features]
+        )
+
+    def predict(self, request):
+        # Get online features from Feast
+        feature_vector = self._get_online_features_from_feast(request)
+
+        # Join features to request features
+        features = request.copy()
+        features.update(feature_vector)
+        features_df = pd.DataFrame.from_dict(features)
+
+        # Apply ordinal encoding to categorical features
+        self._apply_ordinal_encoding(features_df)
+
+        # Sort columns
+        features_df = features_df.reindex(sorted(features_df.columns), axis=1)
+
+        # Drop unnecessary columns
+        features_df = features_df[features_df.columns.drop("zipcode").drop("dob_ssn")]
+
+        # Make prediction
+        features_df["prediction"] = self.classifier.predict(features_df)
+
+        # return result of credit scoring
+        return features_df["prediction"].iloc[0]
+
+    def _get_online_features_from_feast(self, request):
+        zipcode = request["zipcode"][0]
+        dob_ssn = request["dob_ssn"][0]
+
+        return self.fs.get_online_features(
+            entity_rows=[{"zipcode": zipcode, "dob_ssn": dob_ssn}],
+            features=self.feast_features,
+        ).to_dict()
+
+    def is_model_trained(self):
+        try:
+            check_is_fitted(self.classifier, "tree_")
+        except NotFittedError:
+            return False
+        return True

docs/source/_static/img/choose-machine.png

@@ -1,12 +1,17 @@
-# What is a feature store?
-Feature stores are central data stores to power operational machine learning models. They help you store transformed feature values in a scalable and performant database. Real-time inference requires features to be returned to applications with low latency at scale. This is where ScyllaDB can play a crucial role in your machine learning infrastructure.
+# Why ScyllaDB for feature stores?
+Feature store is a central data store to power operational machine learning models. They help you store transformed feature values in a scalable and performant database. Real-time inference requires features to be returned to applications with low latency at scale. This is where ScyllaDB can play a crucial role in your machine learning infrastructure.
 
 [![](https://mermaid.ink/img/pako:eNptkLtuwzAMRX-F4NDJ_gEPBdq62bI0mWp7ICRaFqqHQckpgjj_XtVJOxTlxMe5xCUvqKJmbHB08VNNJBmObR-gxFN3FAppjOJZwwOQMcKGcik0ZRqgrh_hhr50B3V2jtpnqCEGZwNDylHIMAx3ZMPXHWc1QRaywQazLUqcV2i7ffHhfif_qUamvAjDiVXZnVZ4vYsSy-mvZte9Mbk6W89A85wGrNCzeLK6XHv5RnvME3vusSmpJvnosQ_XwtGS4-EcFDZZFq5wmYtPbi0ZIY_NSC6VLmtbbOxv79u-WOFM4T3GH-b6BaPtdAY?type=png)](https://mermaid.live/edit#pako:eNptkLtuwzAMRX-F4NDJ_gEPBdq62bI0mWp7ICRaFqqHQckpgjj_XtVJOxTlxMe5xCUvqKJmbHB08VNNJBmObR-gxFN3FAppjOJZwwOQMcKGcik0ZRqgrh_hhr50B3V2jtpnqCEGZwNDylHIMAx3ZMPXHWc1QRaywQazLUqcV2i7ffHhfif_qUamvAjDiVXZnVZ4vYsSy-mvZte9Mbk6W89A85wGrNCzeLK6XHv5RnvME3vusSmpJvnosQ_XwtGS4-EcFDZZFq5wmYtPbi0ZIY_NSC6VLmtbbOxv79u-WOFM4T3GH-b6BaPtdAY)
 
 
-## How can ScyllaDB help you build a feature store?
-ScyllaDB is a real-time high-throughput NoSQL database that is best suited for feature stores where you require low latency consistently, and need peta-byte scalability.
+## Why should you consider ScyllaDB as feature store?
+ScyllaDB is a real-time NoSQL database that is best suited for feature store use cases where you require low latency (e.g. model serving), high throughout (e.g. training) and need peta-byte scalability.
 
-* **Low-latency**: ScyllaDB can provide <10 ms P99 latency. Low latency can speed up training time and leads to faster model development.
-* **High-throughput**: Training requires huge amounts of data and processing large datasets with many millions of operations per second - something that ScyllaDB excels at.
-* **Large-scale**: ScyllaDB can handle petabytes of data while still providing great performance.
+* **Low-latency**: ScyllaDB can provide <1 ms P99 latency. For real-time machine learning apps, an online feature store is required to meet strict latency requirements. ScyllaDB is an excellent choice for an online store (Read how [Medium is using ScyllaDB](https://medium.engineering/scylladb-implementation-lists-in-mediums-feature-store-part-2-905299c89392) as a feature store.)
+* **High-throughput**: Training requires querying huge amounts of data and processing large datasets with possibly millions of operations per second - something that ScyllaDB excels at
+* **Large-scale**: ScyllaDB can handle petabytes of data while still keeping latency low and predictable great performance.
+* **High availability**: ScyllaDB is a highly available database. With its distributed architecture, ScyllaDB keeps your feature store database always up and running no matter what
+* **Easy to migration**: ScyllaDB is compatible with DynamoDB API and Cassandra which means it's simple to migrate over from legacy solutions.
+* **Integration with Feast**: ScyllaDB integrates well with the popular open-source feature store framework, Feast. Example architecture with Feast and ScyllaDB:
+
+![scylla feast architecture](/_static/img/scylla-feast.jpg)

docs/source/_static/img/feast-ui.png

@@ -12,9 +12,9 @@
 
 # Builds documentation for the following tags and branches.
 TAGS = []
-BRANCHES = ["master"]
+BRANCHES = ["main"]
 # Sets the latest version.
-LATEST_VERSION = "master"
+LATEST_VERSION = "main"
 # Set which versions are not released yet.
 UNSTABLE_VERSIONS = [""]
 # Set which versions are deprecated
@@ -44,7 +44,7 @@
 master_doc = "index"
 
 # General information about the project.
-project = "ScyllaDB feature store example docs"
+project = "Feature Store"
 copyright = str(date.today().year) + ", ScyllaDB. All rights reserved."
 author = u"ScyllaDB Project Contributors"
 
@@ -109,7 +109,7 @@
     "github_issues_repository": "scylladb/scylladb-feature-store",
     "github_repository": "scylladb/scylladb-feature-store",
     "site_description": "ScyllaDB feature store example.",
-    "hide_version_dropdown": ["master"],
+    "hide_version_dropdown": ["main"],
     "versions_unstable": UNSTABLE_VERSIONS,
     "versions_deprecated": DEPRECATED_VERSIONS,
 }