{"id":18368670,"url":"https://github.com/radanalyticsio/jiminy-predictor","last_synced_at":"2025-04-06T17:31:48.300Z","repository":{"id":72027020,"uuid":"104391422","full_name":"radanalyticsio/jiminy-predictor","owner":"radanalyticsio","description":"a predictor service for a spark based recommendation app","archived":false,"fork":false,"pushed_at":"2024-07-10T06:46:53.000Z","size":83,"stargazers_count":2,"open_issues_count":6,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-22T04:02:08.874Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radanalyticsio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-21T19:43:46.000Z","updated_at":"2019-05-01T23:12:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"44fc867a-1811-44b7-92a0-6f28116e1939","html_url":"https://github.com/radanalyticsio/jiminy-predictor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radanalyticsio%2Fjiminy-predictor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radanalyticsio%2Fjiminy-predictor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radanalyticsio%2Fjiminy-predictor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radanalyticsio%2Fjiminy-predictor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radanalyticsio","download_url":"https://codeload.github.com/radanalyticsio/jiminy-predictor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247522402,"owners_count":20952542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T23:26:56.319Z","updated_at":"2025-04-06T17:31:47.994Z","avatar_url":"https://github.com/radanalyticsio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/radanalyticsio/jiminy-predictor.svg?branch=master)](https://travis-ci.org/radanalyticsio/jiminy-predictor)\n\n# Jiminy Predictor\n\nThis is the prediction service for the [Jiminy project](https://radanalytics.io/applications/project-jiminy).\n\n## Setup\n\nTo setup the predictor we will assume that model store is running as a MongoDB with\na `models` database created and that it has been populated with at least one model using the [jiminy modeller](https://github.com/radanalyticsio/jiminy-modeler).\n\nTo create the predictor service in OpenShift, first install the [oshinko](https://radanalytics.io/get-started) \ntools with\n\n```bash\noc create -f https://radanalytics.io/resources.yaml\n```\n\nThe predictor can then instantiated by running\n\n```bash\noc new-app --template oshinko-pyspark-build-dc \\\n  -p GIT_URI=https://github.com/radanalyticsio/jiminy-predictor \\\n  -e MODEL_STORE_URI=mongodb://mongo:mongo@mongodb/models \\\n  -p APP_FILE=app.py \\\n  -p APPLICATION_NAME=predictor\n```\n\nTo access the REST web server from outside OpenShift, you can run\n\n```bash\noc expose svc/predictor\n```\n\nAdditionaly, you can configure the frequency at which the service checks for new models\nfrom the model store by passing the minimum interval (in milliseconds) as the `MODEL_STORE_CHECK_RATE`\nenvironment variable. The default value is 60,000 (1 minute) but can be configured as\n\n```bash\noc new-app --template oshinko-pyspark-build-dc \\\n  # ...\n  -e MODEL_STORE_CHECK_RATE=10000 \\\n  # ...\n```\n\n## REST endpoints\n\nThe predictor service provides two main endpoints, one for retrieving ad-hoc\nrating predictions (given a list of users/products) and a top-k rated products \n(given a user). The [OpenAPI](https://github.com/OAI/OpenAPI-Specification) specification\ncan be found in [docs/openapi.yml]([docs/openapi.yml).\n\n### Ratings\n\nTo request a prediction for specific user/product pairs you can issue a `POST`\nrequest to\n\n```bash\n/prediction/ratings\n```\n\nwith the required pairs specified in the payload. For instance, to request\nthe rating predictions for a user with id `100` regarding products with id `200`\nand `201` we issue\n\n```bash\ncurl --request POST \\\n  --url http://0.0.0.0:8080/predictions/ratings \\\n  --header 'content-type: application/json' \\\n  --data '{\"user\": 100, \"products\": [200, 201]}'\n```\n\nThis will return a unique prediction id for this prediction as\n\n```json\n{\n  \"prediction\": {\n    \"id\": \"944c0d286e4641168f0cfef062f42ab8\",\n    \"products\": [\n      {\n        \"id\": 200,\n        \"rating\": 0.0\n      },\n      {\n        \"id\": 201,\n        \"rating\": 0.0\n      }\n    ],\n    \"user\": 100\n  }\n}\n```\n\nThis prediction id can then be used to retrieve\nthe prediction values by issuing a `GET` request to\n\n```bash\n/prediction/ratings/{id}\n```\n\nIn this example this translates to\n\n```bash\ncurl --request GET \\\n  --url http://0.0.0.0:8080/predictions/ratings/944c0d286e4641168f0cfef062f42ab8\n```\n\nResulting in the server response\n\n```json\n{\n  \"id\": \"944c0d286e4641168f0cfef062f42ab8\",\n  \"products\": [\n    {\n      \"id\": 200,\n      \"rating\": 3.1720593237252634\n    },\n    {\n      \"id\": 201,\n      \"rating\": 3.2489033583433855\n    }\n  ],\n  \"user\": 100\n}\n```\n\n### Rankings\n\nThe rankings endpoint allows to retrieve the `k` highest rated products for a\ngiven user. Similarly to the ratings prediction, we issue a `POST` request to\ncreate a prediction resource, this time to the endpoint\n\n```bash\n/prediction/ranks\n```\n\nspecifying in the payload the user we the predictions for and the number of predictions\nwe need. For instance, to get the `25` highest ranked products for user `100`, we issue:\n\n```bash\ncurl --request POST \\\n   --url http://0.0.0.0:8080/predictions/ranks \\\n   --header 'content-type: application/json' \\\n   --data '{\"user\": 100, \"topk\": 25}'\n```\n\nWe will get in return the unique prediction id as\n\n```json\n{\n  \"prediction\": {\n    \"id\": \"0e583ad221be42758456bd8a9e1fc88a\",\n    \"products\": [],\n    \"topk\": 25,\n    \"user\": 100\n  }\n}\n```\n\nTo retrieve the actual top 25 rank for this user, we use the returned `id` and issue a `GET` request to the\nendpoint:\n\n```bash\n/prediction/ranks/{id}\n```\n\nIn this case, this would be\n\n```bash\ncurl --request GET \\\n   --url http://0.0.0.0:8080/predictions/ranks/0e583ad221be42758456bd8a9e1fc88a\n```\n\nThe resulting response would then include all `25` top rated products for user `100`:\n\n```json\n{\n  \"id\": \"0e583ad221be42758456bd8a9e1fc88a\",\n  \"products\": [\n    {\n      \"id\": 98063,\n      \"rating\": 4.978120923261526\n    },\n    {\n      \"id\": 128812,\n      \"rating\": 4.894847467554492\n    },\n    {\n      \"id\": 130347,\n      \"rating\": 4.884188147789942\n    },\n    {\n      \"id\": 99760,\n      \"rating\": 4.702273918596656\n    },\n    {\n      \"id\": 105968,\n      \"rating\": 4.682071695583521\n    },\n    {\n      \"id\": 95021,\n      \"rating\": 4.422838638920666\n    }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradanalyticsio%2Fjiminy-predictor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradanalyticsio%2Fjiminy-predictor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradanalyticsio%2Fjiminy-predictor/lists"}