====== Personalization ======

Recommendations based on customer history.


===== git =====

https://git.picalike.corpex-kunden.de/picalike/personalization

working version is in master branch


===== Database =====

host: **sandy.picalike.corpex-kunden.de**\\
database: **you_api**


=== collections ===

**shops** gmm and product quantization lookup table for each shop\\
**products** pq vector and image url for each product\\
**customers** fisher vector, purchased products, recommendations and info about the customers


===== Fisher vectors and product quantization =====

A visual vocabulary consisting of all the products from the feed is learned using a mixture of gaussians. The results are saved in the shops collection. The visual vocabulary quantizes the feature space into different cells, and image features are soft-assigned to these cells. The assignments are then aggregated over the images of all the purchased products to obtain a customer representation.

The fisher vector is calculated as follows: for each product we take its features from the feature_db and compute the gradient of the log-likelihood of the image wrt the mixing weight, the mean and the covariance (using diagonal covariance matrices). By averaging the gradients over all products, this yields a customer descriptor of size K(1 + 2d), where d is the dimension of the feature space and K is the number of gaussians. The vector is then normalized and saved in the customer collection.

In order to speed up the search for recommended products, we apply product quantization to the products' fisher vectors. The product quantization is learned over all products in the feed and the lookup table is saved in the shops collection.

The asymmetric distance between the customer's fisher vector and the pq vectors of the products returned by a given solr query is calculated and weighted according to gender and categories. The nearest products are saved in the customer collection together with the query and returned by the API.


===== API =====

[no running service]


=== /add_checkouts ===

<code>
input: {"s_id": <shop id>, "c_id": <customer id>, "p_list": ["prod_ids": [<product id>], "date": <date of purchase, string format: "yyyy-mm-dd">]}
output: "checkout added"
</code>
add new checkout to customer history


=== /add_images ===

<code>
input: {"s_id": <shop id>, "c_id": <customer id>, "p_list": [<product id>]}
output: "images added"
</code>
add images of products to customer history (free products too)


=== /update_cfv ===

<code>
input: {"s_id": <shop id>, "c_id": <customer id>, "start_date": <sting format: "yyyy-mm-dd">, "gmm_name": <name of gmm to be used>}
output: [<fisher vector>]
</code>
calculate fisher vector for customer using products purchased starting from ''%%start_date%%'' until now


=== /update_pqs ===

<code>
input: {"s_id": <shop id>, "gmm_name": <name of gmm to be used>, "q": <query>}
output: "pq for <n> products"
</code>
calculate product quantization code for products in the query result


=== /get_recommended ===

<code>
input: {"s_id": <shop id>, "c_id": <customer id>, "q": <query>, 'n_res': <number of products to return, int>, "gmm_name": <name of gmm to be used>}
output: [<list of products>]
</code>
get recommended products by query or – if recommendations do not exist yet – match given customer with products returned by the query


=== /match ===

input: {“s_id”: <shop id>, “c_id”: <customer id>, “q”: <query>, 'n_res': <number of products to return, int>, “gmm_name”: <name of gmm to be used>}

<code>
output: [<list of products>]
</code>
match given customer with products returned by the query