Simple ML

There are myriad variations of variables that can be used to define a recommendation or similarity 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
Request
Response
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
Response
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"
}
​
Machine Learning - Previous
Intro to ML
Next - Machine Learning
Advanced ML
Last updated 3 weeks ago
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)
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