This documentation is work-in-progress and not released to the public!
What is easyrec?
easyrec is an open source recommendation system providing a low (or no) barrier entrance to high quality recommendations to any portal provider in search for personalization. The access to easyrec is provided through Web services assuring an easy and quick integration. Immediate deployment is possible for web sites (e.g. scripts enclosing API calls, placed in the client's pages, see below). easyrec is not yet another algorithmic framework directed at domain experts with programming skills. Its focus is simple integration; In most cases, the web-based administration interface should be sufficient for configuring easyrec.
What do I actually have when I install the easyrec application?
easyrec is a Java web application running on tomcat with a MySQL database backend. The most important aspect of the application is a Web service (available as REST and SOAP) that allows to send data to and retrieve recommendations from easyrec. A Web based administration interface lets you configure its behavior and analyze the state of the application. One installation can service multiple operators, each of whom can manage recommendations for any number of tenants (e.g. webshops).
Which licenses are available for the use of easyrec?
easyrec is available as an open source project under the GPL license model at sourceforge. For those users who do not want to publish their sources when they develop and distribute proprietary extensions, commercial license-models are provided on a peer-to-peer basis (please contact us at ...)
What are the key features of easyrec?
easyrec generates suggestions - recommendations and rankings - solely based on user actions such as ratings, buys or views/previews of items. Requesting suggestions from and submitting actions to easyrec is provided by different interface techniques which are described in the Integration Guide.
Currently easyrec provides the following item recommendations:
- "Users who bought item A, also bought items B, C, ..." based on buy actions of all users
- "Users who viewed item A, also viewed items B, C, ..." based on view actions of all users
- "Users who rated good item A, also rated good items B, C, ..." based on rating actions of all users
- "Personal recommendations for a user" based on the individual action history of a user
- "Related Items" based on ratings of all users. Note: The kind of the item relation depends on the underlying generators. Currently (version 0.96) an item-item based similarity relation is provided.
Additionally some rankings, are provided:
- "Most bought items" based on buy actions of all users within a time range to be specified
- "Most viewed items" based on view actions of all users within a time range to be specified
- "Most rated items" based on rate actions of all users within a time range to be specified
- "Best rated items" based on rate actions of all users within a time range to be specified
- "Worst rated items" based on rate actions of all users within a time range to be specified
Furthermore easyrec comes with a rich administration tool which allows you to control and tune the personalization engine. A quick tour is provided in the User Guide.
How can I evaluate easyrec?
Furthermore, we are hosting a public evaluation instance of the latest version of easyrec. Feel free to integrate this service into your applications. For further information on how to use the evaluation service have a look at http://www.easyrec.org/getstarted.
How can I get easyrec?
easyrec is an open source project hosted at sourceforge (http://sourceforge.net/projects/easyrec/). Download easyrec if you plan to host the recommendation services yourself. Check our blog for any public release updates or feel free to contact us if you are interested in obtaining the latest release candidate.
In the Installation Guide you will learn about the requirements and the necessary steps for setting up an easyrec instance on your server. For upgrading easyrec from an older version read more in the Migration Guide.
How can I integrate easyrec?
Recommendations could be better! How do I tune easyrec?
easyrec comes with several recommendation algorithms as self contained applications called generators. The Tuning Guide explains how to adapt these generators to your specific situation.
How can I extend easyrec?
You can extend the feature set of easyrec by implementing new generators. The Plugin Guide explins how to code such an easyrec plug-in. A complete and well-documented sample is provided in the project easyrec/easyrec-plugins/easyrec-plugins-sample.
How can I support the easyrec development?
If you think that easyrec is lacking some important feature and you want to add it yourself, please have a look at the Coding Guide. It explains easyrec's software architecture and shows how to implement customized recommendation algorithms. Each helping hand is welcome - please contact us (http://www.easyrec.org/contact)!
Moreover, you can support the easyrec development giving a donation at https://sourceforge.net/donate/index.php?group_id=253778!
What's next? Where's the roadmap?
A detailed raodmap of easyrec is currently under development - hence we can provide you with our next hot topics but no detailed schedule right now. The most important up-coming features of easyrec are:
- A flexible Profile-System as the basis to incorporate meta-data such as user- and item-descriptions within the recommendation process
- A refactored Administration-Interface providing more manipulation features (e.g., rule creation, meta-rules, etc.) to the administrator
- Extending the set of the shipped Generators
Deciding for/against easyrec
Will easyrec cope?
At this point, we can only give you some numbers from our demo service:
The most active tenant on the evaluation service on easyrec.org has these statistics:
- ~ 3.7 Million distinct items
- ~ 1 Million distinct users
- ~ 60.000 view actions per day
- ~ 2.500 buy actions per day
It is one of over 1.000 tenants registered at the evaluation service and things are working alright, even though the server machine could use a serious makeover.
Which part of the system will be the bottleneck as I scale things up?
Database size. easyrec's throughput drops drastically when mysql starts paging.
Is easyrec under active development?
We've stopped proactive development for the time being, but we still maintain the codebase, help users in the forum, and do consulting. There is some code we could release but we need sponsors to do that. If you are waiting for a feature, or want to help, please contact us.
Problems with Recommendations
I don't get any recommendations out of easyrec! What can I do?
- Rule generators run only once a day automatically. Before the first run, there won't be any recommendations. Maybe everything works fine?
- You can trigger the rule generator runs. Log in to the application, navigate to Administration and click the puzzle icon ("Start Plugin"). Note: you can't do that in our demo service.
- With default settings, at least 2 different users have to access a set of items before recommendations will be created. Are you sure you did that?
- Are you using the correct host:port/api-method/params?
- Are you using the correct API key?
- Easyrec does not consider all your items if you have many of them. Try one of your most popular ones. If you get recommendations for that one, easyrec works the way we designed it.
- If you have access to the database: truncate the table 'itemassoc' and re-run the rule generators. If there are entries in the 'itemassoc' table afterwards, the recommendations are calculated correctly. Something else is going wrong. (see below)
I still don't get any recommendations out of easyrec! What can I do?
Most probably this is the problem:
- easyrec will show a recommendation only once to any user.
- you are sending the same user id, probably the string "null", along with every single API call
- easyrec sees only one user and will most probably not calculate any recommendations (i.e., 'rules')
- even if it does calculate recommendations, it ships each of them only once, after which event your user "null" has seen them and will not be shown them again
Result: Maybe you are sometimes seeing recommendations, but most of the time you don't, and you can't really reproduce the behavior.
Remedy: send a user id that makes sense or don't send a user id, but don't send the same id for all requests.
Why are recommendations suppressed?
In order to not bore users, easyrec doesn't show recommendations after the user has performed any action (view, buy, rate, or any custom action) in connection with that item.
Which recommendations are suppressed?
All recommendations for items that the current user already knows. i.e., any item that the user has performed an action with (view, buy, rate, or any custom action).
Running Rule Generators
I'm trying the demo service on easyrec.org - can I trigger my generators?
No. At least, we hope not. This feature is protected so that the service goes down only occasionally, not daily.
How can I trigger rule genration?
Log in to the application, select the tenant you want, navigate to Administration and click the puzzle icon ("Start Plugin").
Can I trigger the generators via an API?
No. You have to log in and push the button.
Can I trigger rule generation more than once a day?
Rule Generation dies with an OutOfMemoryError. What can I do?
Your application server doesn't have enough memory. Give it 650M and try again.
Does easyrec consider every possible item combination?
No. The ARM plugin (association rule miner) only considers the top 5000 items with default settings. No other items will show up in otherusersalso* results.
I have many items but I get very few rules, what's going on?
The number of recommendations depends on how your users interact with your items. If you have a very sparse distribution of user actions over items, you won't get a lot of recommendations.
You can get more recommendations if you lower the support percentage, the minimum absolute support, or the confidence percentage.
The ARM plugin only considers the top 5000 items, no matter how many you have. If you want it to consider more, try changing the parameter maxSizeL1, named popular item threshold in the administration view. You'll need more memory and time, but you'll get more recommendations.
How to populate clusters via the API?
The relationship between clusters and items is represented by
BELONGS_TO associations. Therefore you can use the import rule API call to add items to clusters like in the following example:
E.g. to add item 'ItemA' to cluster 'ClusterA' call
About On-line Recommendations
Does easyrec have an on-line recommender?
Do user actions affect recommendations immediately?
Yes and no: New rules are only generated during generator runs. On the other hand, once you view an item, you won't see it in a recommendation again, so the recommendation list changes even without new rules.
Load Balancing Setup
Can easyrec be load balanced over a couple of servers?
There has been no focus on a parallel mode during the development of easyrec and we don't guarantee it works, but we don't see any obvious obstacles which would hinder it. Just make sure that the generators are not running in parallel. You can either set the easyrec.operationMode property in the easyrec.properties file to frontend on all except one instance or schedule the jobs on all instances in a way they don't overlap in their execution times.
What do I use the cluster manager for?
You can use the cluster manager to create hierarchical sets of items. There are API methods to access those items by cluster. Each item may be in any number of clusters. The idea is that you can create sets of items to pick from in certain situations.
Can I get recommendations from item clusters?
No. The recommendation algorithms don't know about the clusters, and the clusters can't be used for filtering, either. You can only put items into clusters in the cluster manager and then retrieve the cluster content via the API. There is some smartness in those methods, like retrieving items from parent clusters if needed.
How are new rules generated for custom action types?
- In the Type Manager add a new association type (the rules created from the new action type will then be of this association type).
- Go to the Administration view and click on the configure tenant icon for your tenant.
- At the lower area of the site you can now select the ARM plugin for the newly created association type.
- Click on the Settings link and insert the name of your new action type in the action type field.
- You can now access the new rules, as soon as the generator has been executed, via a related items API call with the assoctype parameter set to the newly created association type.