Simple ML

There are myriad variations of variables that can be used to define an ML model. So we picked a bunch for you to just plug into when you're ready.

Recommendation Models

The fastest and easiest way to increase your revenue is to offer your customers recommendations for products they would most likely enjoy. These models are good for upselling or recommending additional products for an order.

Also, if you have a large product catalogue, your customers will have difficulties browse through everything and find things they like. Recommenders are an absolute necessity for that case.

Below are our current recommendation models you get out-of-the-box with descriptions of what they do and when they’re the right solution.

Product Recommendations for Users

If you have an established business with a transaction history, this is a great option. It does not require any information about the items or the users themselves, works well with relatively little data and in many cases outperforms more sophisticated models. It uses Item-Based Collaborative Filtering to recommend products to users based on the transaction history of your users and the products they purchased.

• TL;DR: Recommend products based on what similar users liked.

• The model_name for this model is simple_product_recommender.

Content-Based Product Recommendations

This model uses the features , i.e. tags, name and description , of your product to define how they relate to each other and the transaction history to learn what users like. It should be used in cases where transaction data is limited (but not non-existent) while the products’ tags, name or description have enough information to be useful.

• TL;DR: Recommends products based on similar products.

• The model_name for this model is product_content_recommender.

Popular Product Recommendations

As its name suggests, this model recommends the most popular products. This is a very simple version of a recommender, and therefore fairly common. It performs better than random, but is not as sophisticated and effective as others we support. It can be a useful option when data is sparse or as a baseline for comparison with other recommenders.

• TL;DR: Recommend the most popular products.

• The model_name for this model is product_popularity_recommender.

Matrix Factorization Product Recommendations

Models that use Matrix Factorization learn latent factors for each user and product and use them to rank products according to the likelihood a particular user will want a particular product.

This is currently the state-of-the-art algorithm for a recommendation model. It uses transaction history and the features together to get the most out of your data. However, it works best with significantly more data than Collaborative Filtering.

• TL;DR: A complex algorithm that uses your transaction history, users and product content (name, description, tags) to recommend products.

• The model_name for this model is ranking_recommender.

User Recommender for Products

Think of this model as a Lead Generator. It works like the Product Recommendations for Users above, but in reverse. It recommends users based on the likelihood they’ll be interested in a particular product. This kind of information is useful for proactively approaching users or segmenting them based on interest.

• TL;DR: Recommend users based on similar products the users have liked.

• The model_name for this model is simple_user_recommender.

Similarity Models

These models help you find similarities within the Building Blocks User and Products in our system, based on the content of their features or order transaction history.

For example, imagine you’re making an app for a conference. It is supposed to help people find the talks they’ll be interested in. You could assign tags to the talks like "tech" and "sports". Then, your users pick a few tags when they sign in that describe their interests, and the resulting similarity graph recommends which talks to attend. You can also use this feature to help users with similar interests find each other.

• The content calculation is based on term frequency-inverse document frequency; tf–idf.

• These models use the transaction history similarly to the Collaborative Filtering models, finding similarities among your users' behaviors.

Similar Products

This model looks at the transaction history of your users and products. It will return products that are similar to a particular product based on users’ shopping habits.

• TL;DR: Recommend similar products based on their content (name, description, tags)

• The model_name for this model is simple_product_similarity.

• This model depends solely on your transaction history.

Similar Users

Based on the business’s transaction history of their users, this model returns users with shopping habits that are similar to those of a particular user.

• TL;DR: Show similar users based on their content (name, description, tags).

• The model_name for this model is simple_user_similarity.

• This model depends solely on your transaction history.

Similar Tags

This model uses products that have tags assigned to them. By setting output_type to Product, you can get similar products by querying their IDs. Or, you can query using a particular tag, or set of tags, to get the most similar products based on those tags.

• TL;DR: Show similar products based solely on their tags

• The model_name for this model is product_tag_similarity.

• This model requires tags be assigned to products, but doesn’t require any transaction history to work.

Complementary Items

This model is perhaps the one people are most familiar with; people who bought X also bought Y. It can be used for upselling products or recommending products which are frequently bought together. Given a product, it retrieves another set of products that are most commonly bought together with that product.

• TL;DR: Get the most frequent next product from a collection of products

• The model_name for this model is complementary_items .

• The model uses an FP-growth algorithm to provide frequent patterns and to build association rules.

Out of the Box Models

Model	model_name	Features	Data to invoke
Product Recommender for Users	simple_product_recommender	No	User(s)
Content Based Product Recommendations	product_content_recommender	tags, name, description	User(s)
Matrix Factorization Product Recommender	product_factorisation_recommender	No	User(s)
Product Popularity Recommender	product_popularity_recommender	No	"" empty string
Lead Generator	simple_user_recommender	No	User(s)
Similar Products	simple_product_similarity	No	Product(s)
Similar users	simple_user_similarity	No	User(s)
Similar tags	product_tag_similarity	No	Product(s)
Complementary Items	complementary_items	No	Product(s)

Invoke model

Parameters

Body Parameters	Type	Description
data	array	One or more ids to invoke your model with
options	object	Options to specify how you want the result to look like
options.size	number	Number of returned items

Request

POST /ai/models/<model-id>/invoke HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

{
    // See table above to check what data you should send. 
    // Can be one or several items.
    "data": [<PRODUCT_ID OR USER_ID DEPENDING ON MODEL>], 
    "options": {
        "size": 3
    }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "model_name": "simple_product_similarity",
    "result": [
        {
            "predictions": [
                {
                    "distance": 152.0,
                    "output": "5d2852c2f93362000ab82cb0",
                    "rank": 1
                },
                {
                    "distance": 232.0,
                    "output": "5d2849e21a25e1000c7a3881",
                    "rank": 2
                },
                {
                    "distance": 249.0,
                    "output": "5d284bb2f93362000d0ff251",
                    "rank": 3
                }
            ],
            "target": "5d2ed8a8f1fc02000f390db7"
        }
    ],
    "version": "5e32f34fbf48d6000bc49c7a"
}

We recommend invoking models with the expand parameter.See the example bellow.

Request

POST /ai/models/<model-id>/invoke?expand=result.predictions.output HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

{
    "data": ["<product-id>"], 
    "options": {
        "size": 3
    }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "model_name": "simple_product_similarity",
    "result": [
        {
            "predictions": [
                {
                    "distance": 152.0,
                    "output": {
                        "$oid": "5d2852c2f93362000ab82cb0",
                        "_cls": "Product",
                        "_id": {
                            "$oid": "5d2852c2f93362000ab82cb0"
                        },
                        "_sub_products": [],
                        "active": true,
                        "created": {
                            "$date": 1562923714385
                        },
                        "currency": "EUR",
                        "vat": 0.0,
                        [...]
                    },
                    "rank": 1
                },
                {
                    "distance": 232.0,
                    "output": {
                        "$oid": "5d2849e21a25e1000c7a3881",
                        "_cls": "Product",
                        "_id": {
                            "$oid": "5d2849e21a25e1000c7a3881"
                        },
                        "_sub_products": [],
                        "active": true,
                        "created": {
                            "$date": 1562921442170
                        },
                        "currency": "EUR",
                        "vat": 0.0,
                        [...]
                    },
                    "rank": 2
                },
                {
                    "distance": 249.0,
                    "output": {
                        "$oid": "5d284bb2f93362000d0ff251",
                        "_cls": "Product",
                        "_id": {
                            "$oid": "5d284bb2f93362000d0ff251"
                        },
                        "_sub_products": [],
                        "currency": "EUR",
                        "vat": 0.0,
                        [...]
                    },
                    "rank": 3
                }
            ],
            "target": "5d2ed8a8f1fc02000f390db7"
        }
    ],
    "version": "5e32f34fbf48d6000bc49c7a"
}