ckanext-recommendation

ckanext-recommendation provides item recommendations for CKAN. The first version builds item-based collaborative filtering models from normalized implicit interactions, with ckanext-likes implemented as the first production-ready source adapter. The future normalized table source is present only as an architectural stub and is not runnable yet.

Requirements

Compatibility with core CKAN versions:

CKAN version	Compatible?
2.11	yes

Installation

To install ckanext-recommendation:

1. Activate your CKAN virtual environment, for example:

   . /usr/lib/ckan/default/bin/activate

2. Clone the source and install it on the virtualenv

   git clone https://github.com/DataShades/ckanext-recommendation.git cd ckanext-recommendation pip install -e . pip install -r requirements.txt

3. Install and enable ckanext-likes, then apply its migrations. The current MVP uses likes as the only production-ready interaction source:

   pip install ckanext-likes ckan db upgrade -p likes

4. Add recommendation to the ckan.plugins setting in your CKAN config file (by default the config file is located at /etc/ckan/default/ckan.ini).

5. Restart CKAN. For example if you've deployed CKAN with Apache on Ubuntu:

   sudo service apache2 reload

Config settings

Key configuration options:

ckanext.recommendation.enabled = true
ckanext.recommendation.source = likes
ckanext.recommendation.sources = likes
ckanext.recommendation.algorithm = item_cf

ckanext.recommendation.object_types = package
ckanext.recommendation.default_object_type = package
ckanext.recommendation.type_show_actions = {"package": "package_show", "resource": "resource_show"}

ckanext.recommendation.max_limit = 20
ckanext.recommendation.default_limit = 10
ckanext.recommendation.min_interactions_per_item = 1
ckanext.recommendation.min_interactions_per_user = 1

ckanext.recommendation.similarity = cosine
ckanext.recommendation.include_scores_default = false

ckanext.recommendation.cache_enabled = true
ckanext.recommendation.cache_backend = memory
ckanext.recommendation.cache_ttl = 3600

ckanext.recommendation.likes.signal_weight = 1.0
ckanext.recommendation.likes.require_extension = true

ckanext.recommendation.allow_user_id_override = false
ckanext.recommendation.exclude_already_interacted = true

All options are declared with defaults in ckanext/recommendation/config_declaration.yaml, and the extension reads them via tk.config["..."].

ckanext.recommendation.type_show_actions is the explicit contract between recommendation object_type values and CKAN visibility checks. Custom object types must be mapped to their corresponding CKAN *_show action names.

Source notes:

• likes is the current production-ready source.
• table is a reserved stub for the future normalized interaction store and will report itself as unavailable until implemented.
• composite is the glue layer for combining concrete sources.

Actions

The public API is action-based:

• recommendation_item_suggestions
• recommendation_user_suggestions
• recommendation_status_show
• recommendation_rebuild

recommendation_item_suggestions

Returns datasets similar to a subject item using item-based collaborative filtering.

Required parameters:

• id: subject object id
• type: recommendation object type, eg. package

Optional parameters:

• limit
• offset
• exclude_ids
• include_scores

Behavior:

• validates that the subject object exists and is visible to the current user
• filters out recommended objects that are deleted, missing or not accessible
• uses ckanext.recommendation.type_show_actions to resolve visibility checks

Example:

ckan action recommendation_item_suggestions id=<dataset_id> type=package

recommendation_user_suggestions

Returns personalized recommendations for a user profile by aggregating neighbors of the items the user has already interacted with.

Optional parameters:

• user_id
• types
• limit
• offset
• exclude_ids
• include_scores

Behavior:

• if user_id is omitted, the current authenticated user is used
• non-sysadmin users may only request their own recommendations unless ckanext.recommendation.allow_user_id_override = true
• sysadmins may request recommendations for any user
• inaccessible or deleted objects are filtered from the response

Example:

ckan action recommendation_user_suggestions user_id=<user_id> types=package

recommendation_status_show

Returns diagnostic information about the recommendation subsystem.

The response includes:

• whether the extension is enabled
• active source and per-source status details
• configured object types
• type_show_actions mapping
• cache status
• model cache status for configured object type variants

Example:

ckan action recommendation_status_show

recommendation_rebuild

Forces model rebuild and returns resulting model statistics.

Optional parameters:

• types
• source

Behavior:

• sysadmin-only
• bypasses existing cached model and stores a freshly rebuilt one
• returns cache key, source status and model stats such as interaction count, user count, item count and similarity edges

Example:

ckan action recommendation_rebuild types=package

Response shape

Recommendation actions return a common envelope:

• source: resolved interaction source name
• algorithm: recommendation algorithm id
• subject: request subject, eg. item id/type or user id
• count: number of returned results
• results: list of {id, type} objects, with optional score

Demo data

For manual verification you can seed a deterministic recommendation dataset:

ckan recommendation seed-demo-data

To recreate likes for the same fixed demo matrix:

ckan recommendation seed-demo-data --reset

The command creates demo users, datasets and ckanext-likes records from a fixed in-code matrix so that item similarity, personalized recommendations, bridge users, sparse items and low-profile users can all be checked quickly.

Developer installation

To install ckanext-recommendation for development, activate your CKAN virtualenv and do:

git clone https://github.com/DataShades/ckanext-recommendation.git
cd ckanext-recommendation
pip install -e .
pip install -r dev-requirements.txt

Tests

To run the tests, do:

pytest --ckan-ini=test.ini

Releasing a new version of ckanext-recommendation

If ckanext-recommendation should be available on PyPI you can follow these steps to publish a new version:

1. Update the version number in the pyproject.toml file. See PEP 440 for how to choose version numbers.

2. Make sure you have the latest version of necessary packages:

   pip install --upgrade setuptools wheel twine

3. Create a source and binary distributions of the new version:

   python -m build && twine check dist/*
   

   Fix any errors you get.

4. Upload the source distribution to PyPI:

   twine upload dist/*
   

5. Commit any outstanding changes:

   git commit -a
   git push
   

6. Tag the new release of the project on GitHub with the version number from the setup.py file. For example if the version number in setup.py is 0.0.1 then do:

   git tag 0.0.1
   git push --tags
   

License

AGPL