HapiGER βeta

Scalable, Easy Recommendations

Increase your user engagement and sales with good recommendations



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



Create a Namespace

The first thing to do is to create a namespace, which is a bucket that person events are put into:

curl -X POST 'http://localhost:3456/namespaces' -d'{
    "namespace": "movies"
  }'



Create some Events

An event occurs when a person actions something, e.g. Alice views Harry Potter:

curl -X POST 'http://localhost:3456/events' -d '{
    "events": [
    {
      "namespace": "movies",
      "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/events' -d '{
    "events": [
    {
      "namespace": "movies",
      "person":    "Bob",
      "action":    "view",
      "thing":     "Harry Potter"
    }
  ]
}'

When a person actions and thing, it serves two purposes in HapiGER:

  1. It is used to measure a persons similarity to other people
  2. It can be a recommendation of that thing

For example, when Bob buys LOTR

curl -X POST 'http://localhost:3456/events' -d '{
    "events": [
    {
      "namespace":  "movies",
      "person":     "Bob",
      "action":     "buy",
      "thing":      "LOTR",
      "expires_at": "2016-10-12"
    }
  ]
}'

This is an action that can be used to find similar people AND it can be seen as Bob recommending LOTR. For an event to be a recommendation as well it must have an expiration date set with expires_at, which is how long the recommendation will be available for.



Recommendations

Recommendations can be generated by either passing the name of a person or a thing, the namespace to generate recommendations from, and a configuration which defines how to search for recommendations. The configuration is passed to GER and the available variables are listed in the GER Documentation.

What movies should we recommend Alice?

curl -X POST 'http://localhost:3456/recommendations' -d '{
    "namespace": "movies",
    "person": "Alice",
    "configuration": {
      "actions" : {"view": 5, "buy": 10}
    }
}'

will return:

{
  "recommendations": [
    {
      "thing": "LOTR",
      "weight": 0.44721359549996,
      "last_actioned_at": "2015-10-12T17:04:14+01:00",
      "last_expires_at": "2016-10-12T01:00:00+01:00",
      "people": [
        "Bob"
      ]
    }
  ],
  "neighbourhood": {
    "Bob": 0.44721359549996,
    "Alice": 1
  },
  "confidence": 0.00036398962692384
}

Alice should buy LOTR as it was recommended by Bob with a weight of about 0.4.


What movies should we recommend to someone looking at Harry Potter?

curl -X POST 'http://localhost:3456/recommendations' -d '{
    "namespace": "movies",
    "thing": "Harry Potter",
    "configuration": {
      "actions" : {"view": 5, "buy": 10}
    }
}'

returns

{
  "recommendations": [
    {
      "thing": "LOTR",
      "weight": 0.70710678118655,
      "last_actioned_at": "2015-10-13T08:53:00.885Z",
      "last_expires_at": "2016-10-12T00:00:00.000Z",
      "people": [
        "Bob"
      ]
    }
  ],
  "neighbourhood": {
    "LOTR": 0.70710678118655
  },
  "confidence": 0.0010667601060058
}

The person should buy LOTR as it was recommended by Bob with a weight of about 0.7.

The confidence of these recommendations is low because there are not many events in the system. As you add events the confidence will increase



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

curl -X POST 'http://localhost:3456/compact' -d '{
  "namespace": "movies"
}'



Namespaces

Namespaces are used to separate events for different applications or categories of things. You can create namespaces by:

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

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

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



Clients

  1. Node.js client ger-client