{"id":19647071,"url":"https://github.com/idsia/adapquest","last_synced_at":"2026-05-07T03:34:01.618Z","repository":{"id":45638986,"uuid":"369184637","full_name":"IDSIA/adapquest","owner":"IDSIA","description":"ADAPtive QUESTtionnaire, an IDSIA tool for adaptive tests, surveys, and questionnaires.","archived":false,"fork":false,"pushed_at":"2023-10-26T07:15:21.000Z","size":762,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-09T21:53:36.442Z","etag":null,"topics":["adaptive","bayesian","credal","credal-models","crema","imprecise-probability","inference","machine-learning","survey","tool"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IDSIA.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}},"created_at":"2021-05-20T11:28:57.000Z","updated_at":"2021-12-03T09:05:12.000Z","dependencies_parsed_at":"2022-09-10T18:00:43.222Z","dependency_job_id":"a7bd42bb-94e0-43af-b551-1b42b123bf70","html_url":"https://github.com/IDSIA/adapquest","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IDSIA%2Fadapquest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IDSIA%2Fadapquest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IDSIA%2Fadapquest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IDSIA%2Fadapquest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IDSIA","download_url":"https://codeload.github.com/IDSIA/adapquest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240953578,"owners_count":19884039,"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":["adaptive","bayesian","credal","credal-models","crema","imprecise-probability","inference","machine-learning","survey","tool"],"created_at":"2024-11-11T14:42:15.719Z","updated_at":"2026-05-07T03:34:01.576Z","avatar_url":"https://github.com/IDSIA.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"docs/logo.png\" alt=\"Adapquest\" width=\"480\"/\u003e\n\n**ADAP**tive **QUEST**ionnarie is a web-based microservice tool that permit the creation of adaptive tests, surveys,\nand questionnaires based on a pool of questions and a graphical model.\n\nThe idea behind this project, is to have a simple way to assess the _skill level_ of a person based on a series of\nquestions. A skill is considered a particular detail of a person that can be identified with the right questions. The\nadaptive engine aims to find the optimal question for a user in order to maximize the score of the skills.\n\nThis tool is based on the [CreMA](https://github.com/IDSIA/crema) library, also developed\nby [IDSIA](https://github.com/IDSIA).\n\n# Content\n\nThis repository is composed by three different modules:\n\n* the `Backend` that contains the adaptive engine;\n\n* the `Exchange` library, a _Java_ library that can be used to build remote clients for the adaptive engine; and\n\n* the `Experiments` module: a module that uses the `Backend` and the `Exchange` library to perform academic experiments\n  with adaptive surveys.\n\nIn addition, the `Backend` module is also available as a **Docker** image and in a ready to use `docker-compose` format.\n\n# Characteristics\n\nThis tool allows the user to build a survey with an _adaptive_ choice of the questions. In other words, the next\nquestions depends on the model and the previous answers of a person.\n\nFor each survey/questionnaire, a unique `access code` allows multiple person to complete the questions in an anonymous\nway. Each survey has its own `model` that can be crafted to the specific scenarios and questions available.\n\nSome configurations are available, such as:\n\n- limiting the adaptivity using minimum and maximum number of question, and minimum and maximum scoring parameters;\n- limit the order of the questions can be posed;\n- group the questions by skill, depending on the structure of the used model.\n\nEach answer given by a person update its internal `state`. The history of all the answers given and the states produced\ncan be used to follow the evolution of the distributions of probability associated with the questionnaire.\n\nFor details on the model creation, check the documentation for the [CreMA](https://github.com/IDSIA/crema) library. For\nan in depth analysis of the available options, check the [Wiki](https://github.com/IDSIA/adapquest/wiki).\n\n# Usage\n\n## Execution\n\nOnce compiled, the simplest way to run the tool and access to the demo page is to first set these two environment\nvariables:\n\n```bash\nDB_DBMS=memory\nMAGIC_API_KEY=\u003cput there a random string\u003e\n```\n\nThese two settings allows the application to run with an *in-memory* database and init the remote api key.\n\nFinally, run the build jar as following:\n\n```bash\njava -jar adapquest-backend.jar\n```\n\nThe demo page will be accessible at the url http://localhost:8080/demo/.\n\nThis configuration is **not** suitable for a production environment and should be used only to check the demo or be used\nfor experiments. For something production-ready-more-or-less rad the next section.\n\n## Docker image\n\nThe easiest way to run the tool, is to use the **Docker** image. Using the provided `docker-compose.yaml` it is possible\nto have a running application in few minutes reachable on port `:8080`.\n\nThe stack is composed by a database for storing the questions and the session and the backend engine. We\nchose `Postgres 13.1` but any other SQL-based engine supported by *Hibernate* should be compatible.\n\nRefer to the [Wiki](https://github.com/IDSIA/adapquest/wiki) for more details on the `docker-compose` configuration.\n\n\u003e **Note:** to change the context path of the application it is possible to use the environment variable `SERVER_SERVLET_CONTEXT-PATH`.\n\n## Personalization\n\nIt is possible to change the title of the page using the following environment variable:\n\n```\nADAPQUEST_PAGE_TITLE: \"AdapQuest\"\n```\n\nIf it is required to have an _exit button_, a button that can bring the survey token outside the AdapQuest platform, it is possible to use the following two environment variables.\n\n```\nADAPQUEST_EXIT_URL: \"\u003csome valid url\u003e\"\nADAPQUEST_EXIT_TEXT: \"\u003cthe text to show\u003e\"\n```\n\nThe required token will be available in the `sid` field.\n\n\n## Keycloak integration\n\nIt is possible to use Keycloak as identity provider instead of the simple internal mechanism based on APIkey.\n\n### Keycloak client entry\n\nIn order to do so, first create a new `client` on Keycloak by assigning a new `client-id`.\nThis client need to have `openid-connect` as _Client Protocol_ and `confidential` as _Access Type_.\nFields `Valid Redirect URIs` and `Web Origins` can be set to the deployment location or to `*`.\n\nIn the page _Credentials_ generate and copy the `Secret` field.\n\n### Environment variables\n\nThen on the deployment environment variables, set them as following:\n\n* `KEYCLOAK_ENABLED` set to `true` to enable the Keycloak integration;\n* `KEYCLOAK_REALM` set to the value of the application realm;\n* `KEYCLOAK_AUTH_SERVER_URL` set to the authentication server url (ex. `http://keycloak.example.com/auth`);\n* `KEYCLOAK_RESOURCE` set as the `client-id` assigned in Keycloak for this application;\n* `KEYCLOAK_CREDENTIALS_SECRET` set as the generated `Secret` as above;\n* `ADAPQUEST_KEYCLOAK_FIELD`: set the filed to store in the database, if missing or set as empty (`\"\"`) nothing is stored.\n\nDefault fields are: _email, username, birthdate, name, family_name, nickname, given_name, middle_name, phone_number, website_. For custom fields, assign new _scopes_ to the client. \n\n### Application roles\n\nThe application can have two types of roles: a generic role, and an administrative role.\n\nThe generic role (`ADAPQUEST_KEYCLOAK_ROLE`) is to allow only users that have the specified role to be able to perform the survey.\nIf this variable is empty (`\"\"`) then all users can access to the surveys.\n\nThe administrative role (`ADAPQUEST_KEYCLOAK_ADMIN`) is only used to update and manage surveys through the admin console.\n\n### Docker-compose\n\nAll these variables can be used in a `docker-compose` file.\n\n# Citation\n\nIf you write a scientific paper describing research that made use of the `AdapQuest` tool, please see the [CreMA](https://github.com/IDSIA/crema#citation) library citation note.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidsia%2Fadapquest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidsia%2Fadapquest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidsia%2Fadapquest/lists"}