I am proud to announce the beta version of HapiGER an open-source, easy to use, easy to integrate recommendations engine. It is built using the Good Enough Recommendations (GER) engine and the Hapi.js framework.

In this post I will describe how you can use HapiGER to generate recommendations for your users.

Install HapiGER

Install with npm

npm install -g hapiger

Start HapiGER

By default it will start with an in-memory event store (events are not persisted)

hapiger

There are also PostgreSQL and RethinkDB event stores for persistence and scaling

Give an Action Weight

Set the view action to have weight 1:

curl -X POST 'http://localhost:3456/default/actions' -d'{

"name": "view",

"weight": 1

}'

Create some Events

Alice views Harry Potter

curl -X POST 'http://localhost:3456/default/events' -d '{

"person":"Alice",

"action": "view",

"thing":"Harry Potter"

}'

Then, Bob also views Harry Potter (now Bob has similar viewing habits to Alice)

curl -X POST 'http://localhost:3456/default/events' -d '{

"person":"Bob",

"action": "view",

"thing":"Harry Potter"

}'

Bob then buys The Hobbit

curl -X POST 'http://localhost:3456/default/events' -d '{

"person":"Bob",

"action": "buy",

"thing":"The Hobbit"

}'

Get Recommendations

What books should Alice buy?

curl -X GET "http://localhost:3456/default/recommendations?\

person=Alice\

&action=buy" {

"recommendations":[

{

"thing":"The Hobbit",

"weight":0.22119921692859512,

"people":[

"Bob"

],

"last_actioned_at":"2015-02-05T05:56:42.862Z"

}

],

"confidence":0.00019020140391302825,

"similar_people":{

"Bob":1

}

}

Alice should buy The Hobbit as it was recommended by Bob with a weight of about 0.2.

The confidence of these recommendations is pretty low because there are not many events in the system

How HapiGER Works (the Quick Version)

The HapiGER API calculates recommendations for Alice to buy by:

Finding people that are like Alice by looking at her past events Calculating the similarities between Alice and those people Look at the recent things that those similar people buy Weight those things using the similarity of the people

If you would like to read more about how HapiGER works, here is the long version.

Event Stores

The “in-memory” memory event store is the default, this will not scale well or persist event so is not recommended for production.

The recommended event store is PostgreSQL, which can be used with:

hapiger --es pg --esoptions '{

"connection":"postgres://localhost/hapiger"

}'

Options are passed to knex.

HapiGER also supports a RethinkDB event store:

hapiger --es rethinkdb --esoptions '{

"host":"127.0.0.1",

"port": 28015,

"db":"hapiger"

}'

Options passed to rethinkdbdash.

Compacting the Event Store

The event store needs to be regularly maintained by removing old, outdated, or superfluous events; this is called compacting. This can be done either synchronously or asynchronously (it can take a while):

curl -X POST 'http://localhost:3456/default/compact' curl -X POST 'http://localhost:3456/default/compact_async'

Namespaces

Namespaces are used to separate events for different applications or categories of things. The default namespace is default, but you can create namespaces by:

curl -X POST 'http://localhost:3456/namespace' -d'{

"namespace": "new_ns"

}'

To delete a namespace (and all its events!):

curl -X DELETE 'http://localhost:3456/namespace/new_ns'

Configuration of HapiGER

There are many configuration variables for HapiGER to tune the generated recommendations, these can be viewed with hapiger — help. The impact of each of these options are described in the long version of how HapiGER works.

Clients