Back to main page

Recommend

Recommend API is used for recommending a decision to maximize the given goal likelihood

Description

Recommend can be used to 1) make a decision, that 2) optimizes a goal in 3) a specified situation/context

For example, you can ask Aito to 1) choose a product, that 2) maximized click likelihood, when 3) query is 'laptop' and user id is 4543.

Recommend differs from predict/match in the following way: recommend always optimizes a goal, while predict/match merely mimics the old behavior. As an example, consider the problem of project staffing. With predict/match: you can mimic the way the projects are staffed currently, and aito will mimic both the good and the bad staffing practices, as long these remain popular. With recommend: aito seeks to maximize the success rate and avoid decisions that lead to bad outcomes, even if these decisions were a popular practice.

API end point

/api/v1/_recommend

Format:

    {
      "from" : From, 
      "where" : null | Proposition, 
      "recommend" : Get, 
      "goal" : Proposition, 
      "select" : null | Selection, 
      "offset" : null | long, 
      "limit" : null | long
    }

See also:

Example Recommend Query

Recommend a product, that optimizes the click likelihood, given a user and a previous purchase (id 0 is for an iphone)

POST /api/v1/_recommend

    {
       "from" : "impressions",
       "where": {
         "customer" : 4,
         "prevProduct" : 0
       },
       "recommend":"product",
       "goal":{"click":true},
       "limit" : 2
    }

Result

The above query returns an array of results, sorted by probability

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "$p" : 0.494601323286767,
        "description" : "protect iphone with a white phone cover",
        "id" : 6,
        "name" : "iphone_cover_white",
        "price" : 25.0,
        "tags" : "cover",
        "title" : "iphone protection white"
      }, {
        "$p" : 0.407119886979975,
        "description" : "protect iphone with an amazing and premium leather phone cover",
        "id" : 7,
        "name" : "iphone_cover_leather",
        "price" : 25.0,
        "tags" : "cover",
        "title" : "iphone protection leather"
      } ]
    }

Recommend Query with highlights

Same as before, but with highlights field selected

POST /api/v1/_recommend

    {
       "from" : "impressions",
       "where": {
         "customer" : 4,
         "prevProduct" : 0
       },
       "recommend":"product",
       "goal":{"click":true},
       "select": ["id", "$highlight", "$p"],
       "limit" : 1
    }

Result

The above query returns an array of results, sorted by probability

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "id" : 6,
        "$highlight" : [ {
          "score" : 1.8923690856935902,
          "field" : "description",
          "highlight" : "protect iphone <font color=\"red\">with</font> a <font color=\"red\">white</font> <font color=\"red\">phone</font> cover"
        }, {
          "score" : 1.5640006365638852,
          "field" : "title",
          "highlight" : "<font color=\"green\">iphone</font> <font color=\"green\">protection</font> <font color=\"green\">white</font>"
        }, {
          "score" : 0.2733178796333847,
          "field" : "price",
          "highlight" : "<font color=\"green\">25.0</font>"
        } ],
        "$p" : 0.494601323286767
      } ]
    }

Recommend Query with diagnostics

Same as before, but with why field selected

POST /api/v1/_recommend

    {
       "from" : "impressions",
       "where": {
         "customer" : 4,
         "prevProduct" : 0
       },
       "recommend":"product",
       "goal":{"click":true},
       "select": ["id", "$why", "$p"],
       "limit" : 1
    }

Result

The above query returns an array of results, sorted by probability

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "id" : 6,
        "$why" : {
          "type" : "product",
          "factors" : [ {
            "type" : "hitVariableLift",
            "variable" : "description:phone",
            "value" : 0.39435825547631354,
            "factors" : [ {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.id:0",
              "value" : 0.6419518126999181
            }, {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.title:appl",
              "value" : 0.6143113044851815
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(title:appl)",
            "value" : 0.5690732971228674,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 0.8335082316769677
            }, {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.title:appl",
              "value" : 0.8477343271061256
            }, {
              "type" : "relatedVariableLift",
              "variable" : "customer:4",
              "value" : 0.8053757428759326
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "title:protect",
            "value" : 1.6545155886213592,
            "factors" : [ {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.id:0",
              "value" : 1.861376215457214
            }, {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.title:appl",
              "value" : 0.8888668367425963
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "title:iphon",
            "value" : 1.4923928473432801,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 1.1270433810818277
            }, {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.id:0",
              "value" : 1.0400049200526507
            }, {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.title:appl",
              "value" : 0.8745750653544029
            }, {
              "type" : "relatedVariableLift",
              "variable" : "customer:4",
              "value" : 1.455827909848681
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(tags:premium)",
            "value" : 0.7232947780347334,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 0.7232947780347334
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "description:white",
            "value" : 0.7591187388382302,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 0.7591187388382302
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "price:25.0",
            "value" : 1.2085841103008568,
            "factors" : [ {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.id:0",
              "value" : 1.4182493168858188
            }, {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.title:appl",
              "value" : 0.852166185388798
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "title:white",
            "value" : 1.197449156911402,
            "factors" : [ {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.id:0",
              "value" : 1.197449156911402
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(price:1500.0)",
            "value" : 0.866508541593727,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 0.866508541593727
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "description:with",
            "value" : 0.8997865425847966,
            "factors" : [ {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.id:0",
              "value" : 1.0299570503629785
            }, {
              "type" : "relatedVariableLift",
              "variable" : "customer:4",
              "value" : 0.8736155961723773
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(description:acm)",
            "value" : 1.110831846452614,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 1.110831846452614
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(description:common)",
            "value" : 1.110831846452614,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 1.110831846452614
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(description:premium)",
            "value" : 0.9004777825612722,
            "factors" : [ {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.title:appl",
              "value" : 0.9004777825612722
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(tags:phone)",
            "value" : 0.9009803086403873,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 0.9009803086403873
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(tags:laptop)",
            "value" : 0.9087127990549599,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 0.9087127990549599
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(id:4)",
            "value" : 1.100268354602856,
            "factors" : [ {
              "type" : "relatedVariableLift",
              "variable" : "customer:4",
              "value" : 1.100268354602856
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(description:amaz)",
            "value" : 0.9169421170782404,
            "factors" : [ {
              "type" : "relatedVariableLift",
              "variable" : "prevProduct.id:0",
              "value" : 0.9169421170782404
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(description:awesom)",
            "value" : 1.0353259634187941,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 1.0353259634187941
            } ]
          }, {
            "type" : "hitVariableLift",
            "variable" : "not(description:idea)",
            "value" : 1.0177852276776407,
            "factors" : [ {
              "type" : "baseLift",
              "value" : 1.0177852276776407
            } ]
          } ]
        },
        "$p" : 0.494601323286767
      } ]
    }

Smart Searching Recommend Query

Recommend a product, that optimizes the click likelihood, when the query is 'cheap phone'. If there is a history of term matches between some context fields (like query), and the matched item: Aito will be able to recognize this with the analogy mechanism, and enable the term matching.

The analogies unify statistical inference (the pattern where 'query:best' implies 'product.tags:"premium"') and full-text search (the pattern where 'query:X' implies 'product.title:X', where X can be an arbitrary term). This is done by supplementing the statistical inference with a Bayesian prior, that is based on the aggregated term match statistics.

POST /api/v1/_recommend

    {
       "from" : "impressions",
       "where": {
         "query" : "cheap phone"
       },
       "recommend":"product",
       "goal":{"click":true},
       "select":["title", "description"],
       "limit" : 1
    }

Result

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "title" : "huawei honor",
        "description" : "huawei is an affordable android phone"
      } ]
    }

Recommend Query with narrowed results

Recommend a laptop product, that optimizes the click likelihood'. The Example uses where-clause to set constraints on the returned results.

POST /api/v1/_recommend

    {
       "from" : "impressions",
       "where": {
         "product.tags" : {"$match":"laptop"}
       },
       "recommend":"product",
       "goal":{"click":true},
       "select":["title", "description"],
       "limit" : 1
    }

Result

    {
      "offset" : 0,
      "total" : 3,
      "hits" : [ {
        "title" : "apple macbook",
        "description" : "apple macbook is the top laptop in the market"
      } ]
    }

Recommend Query with chat context

Recommend a product, that optimizes the click likelihood, when user asks for a product recommendation

POST /api/v1/_recommend

    {
       "from" : "impressions",
       "where": {
         "messageContext.message" : "Recommend me a premium android phone"
       },
       "recommend":"product",
       "goal":{"click":true},
       "select":["title", "description"],
       "limit" : 1
    }

Result

    {
      "offset" : 0,
      "total" : 11,
      "hits" : [ {
        "title" : "samsung s8",
        "description" : "samsung s8 is a premium phone with all sorts of features "
      } ]
    }

Recommending linked items and text field features

Recommend product tags for maximal click through rate. This mechanism can be used for e.g. proposing relevant product pages (e.g. see android phones) or ordering the product filters by relevance in the search page.

Note, how the recommendation clause refers to the $feature field. This is aito's syntax for accessing the features of the text field.

Because the text fields are analyzed, there are two different kinds of interesting data in the text field:

  1. The text field values (e.g. "Apple iPhone")
  2. And the analyzed terms/features (e.g. "title":"appl", "title":"iphone")

If you recommend the text field (e.g. "recommend":"text"), aito will return the text field values by default. In order to recommend terms/features, you need to use the $feature syntax as shown in the following example.

POST /api/v1/_recommend

    {
       "from" : "impressions",
       "where": {
         "query" : "cheap phone"
       },
       "recommend" : "product.tags.$feature",
       "goal": {"click":true},
       "limit" : 3
    }

Result

    {
      "offset" : 0,
      "total" : 9,
      "hits" : [ {
        "$p" : 0.29192019411075704,
        "field" : "",
        "feature" : "phone"
      }, {
        "$p" : 0.2647517501484349,
        "field" : "",
        "feature" : "afford"
      }, {
        "$p" : 0.09730123537603426,
        "field" : "",
        "feature" : "io"
      } ]
    }