elphas/recommender

The Elphas recommender is a service for your data. Send in the data, we do some analises and you get back recommendations.

dev-master 2019-10-15 09:32 UTC

Requires

• php: >=5.6
• guzzlehttp/guzzle: ^6.3

AGPL-3.0-only

• Gerben Robijn

README

The Elphas recommender is a recommendation service for your data. Send in the data, we do some analyses and you get back recommendations.

How to install
What does it do
How to use
Support

How to install

Go to your Laravel project where you would like to use Elphas Recommender and install via composer:

composer require elphas/recommender 

Register API key and secret key for your app in the .env file

RECOMMENDER_APIKEY=<your-api-key-here>
RECOMMENDER_SECRETKEY=<your-secret-key-here>

No Api key yet?

Sign up here: http://test.developer.elphas.ai.
Create your first app and enter the keys in the .env file.

What does it do

The Elphas recommender is a recommendation service for your data. Send in the data, we do some analyses and you get back recommendations.

Let's look at an example:
If you have a user base who all have certain skills and you want to give your user suggestions on what to learn next.

What you would do with Elphas Recommender is the following:

You would create a collection ( this is a container for your specific data ) and supply it with the profiles. This can be done with complete anonymity.
A profile would look something like this:

{
   "id":1357, //this is an ID generated by us
   "items": //a set of skills that you supply for that user
   [
   	"html5",
   	"java"
   ],
   "reference_id":1 //this is an ID that perhaps matches an ID in your system for easier lookups later on
}

Based on a couple of profiles we can supply your profile with recommendation. Based on a collection with the above profile we could recommend the following:

{
   "augment":
   [
   	"mysql",
   	"php"
   ],
   "recommendation":
   [
   	"android",
   	"css3",
   	"jquery",
   	"wordpress",
   	"spring",
   	"ios",
   	"mysql",
   	"ajax",
   	"php",
   	"tomcat"
   ]
}

You could use different strategies to get recommendations. Read more about strategies

How to use

Collections

List of your collections

Recommender::getCollections();

Create new collection

Recommender::postCollection( 'Name of the collection' );

Get specific collection by collection ID

Recommender::getCollection( $collectionId );

Change the name of the collection

Recommender::patchCollection( $collectionId, $name )

Delete the collection
Be careful with this :)

Recommender::deleteCollection( $collectionId );

Items

Get the unique items in a collection

Recommender::getItems( $collectionId );

Profiles

Get all profiles of a collection

Recommender::getProfiles( $collectionId );

Create new profile in a collection

$profile = new \Elphas\Recommender\Profile();
$profile->items = [ 'laravel', 'vue', 'php', 'javascript' ];
Recommender::postProfile( $collectionId, $profile );

//or

$profile2 = new \Elphas\Recommender\Profile( null, null, [ 'laravel', 'vue', 'php', 'javascript' ] );
Recommender::postProfile( $collectionId, $profile2 );

Supply a reference id so that you can match the profile with your own system

$profileWithRef = new \Elphas\Recommender\Profile( null, $referenceId, [ 'laravel', 'vue', 'php', 'javascript' ] );
Recommender::postProfile( $collectionId, $profileWithRef );

Get a profile in a collection

Recommender::getProfile( $collectionId, $profileId);

//by your reference ID

Recommender::getProfile( $collectionId, $referenceId, true);

//as an Elphas Profile instance

$profile = Recommender::getProfile( $collectionId, $profileId, false, true);

Update a profile in a collection

$profile = Recommender::getProfile( $collectionId, $profileId, false, true);

$profile->items[] = 'blade';

Recommender::patchProfile( $collectionId, $profileId, $profile)

Delete a profile in a collection Again be careful with this.

Recommender::deleteProfile( $collectionId, $profileId)

//or by referenceID

Recommender::deleteProfile( $collectionId, $referenceId, true)

Recommendations

Once a collection has been filled with profiles and items we can do a recommendation for a profile, based on the other profiles in the collection.

Recommender::recommend( $collectionId, $profileId)

Recommendations can be done with three strategies: augment, recommend or all.

The default strategy for getting a recommendation is the recommend strategy. The recommend strategy compares profiles with each other.

The augment strategy checks which unique items belong together and how many times this happens.

The all strategy combines the strategies. The result will returned per strategy.

Recommender::recommend( $collectionId, $profileId, 'recommend' )

//or

Recommender::recommend( $collectionId, $profileId, 'augment' )

//or 

Recommender::recommend( $collectionId, $profileId, 'all' )

When using the augment strategy you will be able to supply a minimal quality setting between 0 and 1.
The higher the quality the more strict a recommendation will be.

Recommender::recommend( $collectionId, $profileId, 'augment', 0.7 )

There is an option to limit the number of recommendations. The default is 10:

Recommender::recommend( $collectionId, $profileId, 'augment', 0.7, 5 )

Recommendations based on your own referenceID is also possible:

Recommender::recommend( $collectionId, $referenceId, 'augment', 0.7, 5, true )

Support

Email us at [e-mail]