{"id":47311131,"url":"https://github.com/inception-project/inception-external-recommender","last_synced_at":"2026-03-17T11:29:43.776Z","repository":{"id":44572646,"uuid":"215540458","full_name":"inception-project/inception-external-recommender","owner":"inception-project","description":"Get annotation suggestions for the INCEpTION text annotation platform from spaCy, Sentence BERT, scikit-learn and more. Runs as a web-service compatible with the external recommender API of INCEpTION.  ","archived":false,"fork":false,"pushed_at":"2025-11-10T19:32:52.000Z","size":1327,"stargazers_count":47,"open_issues_count":16,"forks_count":24,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-11-10T21:17:20.682Z","etag":null,"topics":["annotation","inception-recommender","machine-learning","natural-language-processing","spacy"],"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/inception-project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-10-16T12:16:24.000Z","updated_at":"2025-11-10T19:26:42.000Z","dependencies_parsed_at":"2024-03-05T09:42:30.030Z","dependency_job_id":"65ae89b1-b8db-455d-97b8-a831ebdb36ca","html_url":"https://github.com/inception-project/inception-external-recommender","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/inception-project/inception-external-recommender","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inception-project%2Finception-external-recommender","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inception-project%2Finception-external-recommender/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inception-project%2Finception-external-recommender/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inception-project%2Finception-external-recommender/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inception-project","download_url":"https://codeload.github.com/inception-project/inception-external-recommender/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inception-project%2Finception-external-recommender/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30622675,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T11:26:08.186Z","status":"ssl_error","status_checked_at":"2026-03-17T11:24:37.311Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["annotation","inception-recommender","machine-learning","natural-language-processing","spacy"],"created_at":"2026-03-17T11:29:42.328Z","updated_at":"2026-03-17T11:29:43.772Z","avatar_url":"https://github.com/inception-project.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# inception-external-recommender\n\n[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\nThis repository provides **[ariadne](https://inception.fandom.com/wiki/Ariadne)**, a library \nto run and implement external recommenders for INCEpTION using Python.\n\nYou can watch external recommender in action in the follwing video:\n\n[![Alt text](https://img.youtube.com/vi/LTgtii7gEWg/0.jpg)](https://www.youtube.com/watch?v=LTgtii7gEWg)\n\n## Install required packages\n\nThis project uses [uv](https://docs.astral.sh/uv/) for fast, reliable package management. \n\nFirst, install uv if you haven't already:\n\n    pip install uv\n\nThen install the basic requirements:\n    \n    uv pip install -e .\n\nThere are further requirements which need to be fulfilled depending on the use case. They are\nlisted and explained below:\n\n* `contrib` for being able to use the provided already usable external recommenders (for a\n detailed overview see [Contrib Models](#contrib-models) below)\n* `test` for being able to use the tests\n\u003c!--- * `doc` for being able to build the documentation % --\u003e\n* `dev` for being able to develop this package\n\nNote that depending on your system, it may be necessary to install certain system libraries manually\nbefore activating the contrib dependencies. For example on macOS, `libomp` is required by the `lightgbm`\ncontrib dependency:\n\n    brew install libomp\n\nTo install for example the `contrib` dependencies run:\n    \n    uv pip install -e \".[contrib]\"\n\n \n## Starting a simple recommender\n\nWe provide multiple ready to use recommenders. A full overview of them can be found at [Contrib\n Models](#contrib-models).\n \nIn this section we provide an example on how to start a server with two recommenders, one for\nnamed entities and one for parts-of-speech. They both use [spaCy](https://spacy.io/) and are\nnot trainable. \n\nBe aware that the english spacy model needs to be downloaded previously. This can be done by\nrunning:\n    \n    python -m spacy download en_core_web_sm \n\nThen you can use this example code to start the server:\n\n    from ariadne.contrib.spacy import SpacyNerClassifier, SpacyPosClassifier\n    from ariadne.server import Server\n      \n    server = Server()\n    server.add_classifier(\"spacy_ner\", SpacyNerClassifier(\"en_core_web_sm\"))\n    server.add_classifier(\"spacy_pos\", SpacyPosClassifier(\"en_core_web_sm\"))\n\n    server.start()\n    \nThe external recommenders are afterwards reachable under `http://localhost:5000/spacy_ner` and \n`http://localhost:5000/spacy_pos` respectively.\n\nTo add them to your INCEpTION-project open its settings page and choose the tab *Recommenders*. \nClick on *Create* to create a new recommender. Then choose its properties according to the\npicture below to add the part-of-speech recommender. Its name is generated automatically.\n \n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/spacy_pos_settings.png\"\u003e\n\u003c/p\u003e\n\nClick *Save* and open a text for annotation. After performing an action, e.g. making an\nannotation, the recommendations are shown above the tokens. Adding the named-entity recommender\nworks similarly. A detailed description for using a recommender can be found in the \n[INCEpTION user guide](https://inception-project.github.io/releases/21.1/docs/user-guide.html). \n    \n## Building your own recommender\n\nSee `ariadne/contrib/sklearn.py` for examples.\n\n## Deployment\n\nIn order to support multiple users at once, the recommender server needs to be started on\na wsgi server. This can e.g. be done via [gunicorn](https://gunicorn.org/). We provide an\nexample in `wsgi.py` which can be run via\n\n    uv run task serve\n    \nOr directly with gunicorn:\n\n    uv run gunicorn -w 4 -b 127.0.0.1:5000 wsgi:app\n    \nThis runs the recommendation server with 4 workers, that means at least 4 users can use the \nserver at the same time. Make sure to scale this to your needs. Also adjust the IP adress\nthe server is listening on. `0.0.0.0` exposes it to your network!\n\n## Contrib Models\n\nMultiple different models have already been implemented and are ready for you to use. The\nfollowing table provides an overview about them:\n\n| Classname | Description | Trainable |\n| --------- | ----------- | --------- |\n| JiebaSegmenter | Chinese segmentation prediction with [Jieba](https://github.com/fxsjy/jieba) | no |\n| LevenshteinStringMatcher | \"Fuzzy\" string matching | yes |\n| NltkStemmer | Word stemming prediction with [NLTK](https://www.nltk.org/), using its PorterStemmer | no |\n| SklearnMentionDetector | Mention detection with [sklearn-crfsuite](https://github.com/TeamHG-Memex/sklearn-crfsuite), using a conditional random field, trained with gradient descent using the L-BFGS method | yes |\n| SklearnSentenceClassifier | Sentence classification with [scikit-learn](https://scikit-learn.org/stable/), using its multinominal naive bayes classifier and  TF-IDF counts as features | yes |\n| SpacyNerClassifier | Named-entity prediction with [spaCy](https://spacy.io/) | no |\n| SpacyPosClassifier | Part-of-speech prediction with [spaCy](https://spacy.io/) | no |\n| AdapterSequenceTagger | Sequence tagger using [Adapters](https://adapterhub.ml/) | no |\n| AdapterSentenceClassifier | Sentence classifier using [Adapters](https://adapterhub.ml/) | no |\n| FlairNERClassifier | Sequence tagger using [Flair](https://flairnlp.github.io/) | no |\n\nFor using trainable recommenders it is important to check the checkbox *Trainable* when adding\nthe external recommender to your project. To be able to get predictions of a added trainable\nrecommenders you need to start creating annotations in the corresponding layer. \nAfterwards click on the speechbubble-symbol (*Recommendation*) on the left side and choose *Save* \nto train the recommender. Now new predictions will be displayed.\n\nThe contrib models are an example and are intended to be used with INCEpTION, therefore they might not be a\n100% fit for you, e.g. `create_prediction`. If your project uses a different type system than DKPro, then you can\nalter the variables in `inception_util.py`.\n\n### Jieba Segmenter\n\nThis recommender uses [Jieba](https://github.com/fxsjy/jieba) for predicting Chinese segmentation.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/jieba.png\"\u003e\n\u003c/p\u003e\n\n### S-BERT sentence classifier\n\nThis recommender uses [S-BERT](https://github.com/UKPLab/sentence-transformers) together with\n[LightGBM](https://lightgbm.readthedocs.io/en/latest/) for sentence classification.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/sbert_sls.png\"\u003e\n\u003c/p\u003e\n\n## Development\n\nThe following section describes how to develop your own recommender. **inception-recommender** \ncomes with example requests which can be found in `examples/requests`.\n\n### Available Tasks\n\nWe use [taskipy](https://github.com/illBeRoy/taskipy) for common development tasks:\n\n    uv run task test     # Run tests\n    uv run task serve    # Start development server with hot-reload\n    uv run task format   # Format code with ruff\n    uv run task lint     # Check code with ruff linter\n    uv run task fix      # Auto-fix linting issues\n\n### Tester\n\nThe tester allows to send different requests to your external recommender, thereby you\ndo not need to run INCEpTION during (early) development.\n\n    $ uv run python scripts/tester.py train -h\n    usage: tester.py [-h] [-u USER] {train,predict}\n    \n    Test your INCEpTION external recommender.\n    \n    positional arguments:\n      {train,predict}       The request type you want to use.\n    \n    optional arguments:\n      -h, --help            show this help message and exit\n      -u USER, --user USER  The user issuing the request.\n      \n### Developing in deployment setting\n\nThe simplest way to develop in deployment setting, that is using `gunicorn` is to just run\n\n    uv run task serve\n    \nThis starts `gunicorn` with 4 workers and hot-code reloading.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finception-project%2Finception-external-recommender","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finception-project%2Finception-external-recommender","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finception-project%2Finception-external-recommender/lists"}