{"id":28092946,"url":"https://github.com/uclnlp/jack","last_synced_at":"2025-08-12T02:35:35.767Z","repository":{"id":62586078,"uuid":"63639964","full_name":"uclnlp/jack","owner":"uclnlp","description":"Jack the Reader ","archived":false,"fork":false,"pushed_at":"2019-02-09T09:11:55.000Z","size":29413,"stargazers_count":258,"open_issues_count":27,"forks_count":79,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-07-31T23:31:40.232Z","etag":null,"topics":["deep-learning","knowledge-base","natural-language-inference","natural-language-processing","question-answering","tensorflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uclnlp.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}},"created_at":"2016-07-18T21:58:04.000Z","updated_at":"2025-04-04T12:02:35.000Z","dependencies_parsed_at":"2022-11-03T22:15:53.700Z","dependency_job_id":null,"html_url":"https://github.com/uclnlp/jack","commit_stats":null,"previous_names":["uclmr/jack"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/uclnlp/jack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uclnlp%2Fjack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uclnlp%2Fjack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uclnlp%2Fjack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uclnlp%2Fjack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uclnlp","download_url":"https://codeload.github.com/uclnlp/jack/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uclnlp%2Fjack/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269990111,"owners_count":24508816,"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","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["deep-learning","knowledge-base","natural-language-inference","natural-language-processing","question-answering","tensorflow"],"created_at":"2025-05-13T13:57:53.183Z","updated_at":"2025-08-12T02:35:35.725Z","avatar_url":"https://github.com/uclnlp.png","language":"Python","readme":"# Jack the Reader [![Wercker build badge][wercker_badge]][wercker] [![codecov](https://codecov.io/gh/uclmr/jack/branch/master/graph/badge.svg?token=jbZrj9oSmi)](https://codecov.io/gh/uclmr/jack) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jack-the-reader/Lobby?source=orgpage) [![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)](https://github.com/uclmr/jack/blob/master/LICENSE)\n\n##### A Machine Reading Comprehension framework.\n\n* All work and no play makes Jack a great frame*work*!\n* All work and no play makes Jack a great frame*work*!\n* All work and no play makes Jack a great frame*work*!\n\n[wercker_badge]: https://app.wercker.com/status/8ed61192a5b16769a41dc24c30a3bc6a/s/master\n[wercker]: https://app.wercker.com/project/byKey/8ed61192a5b16769a41dc24c30a3bc6a\n[heres_johnny]: https://upload.wikimedia.org/wikipedia/en/b/bb/The_shining_heres_johnny.jpg\n\n**Jack the Reader** - or **jack**, for short - is a framework for building and using models on a variety of tasks that require *reading comprehension*. For more informations about the overall architecture, we refer to [Jack the Reader – A Machine Reading Framework](https://arxiv.org/abs/1806.08727) (ACL 2018).\n\n## Installation\nTo install Jack, install requirements and [TensorFlow](http://tensorflow.org/). In case you want to use PyTorch for writing models, please install [PyTorch](http://pytorch.org/) as well.\n\n## Supported ML Backends\n\nWe currently support [TensorFlow](http://tensorflow.org/) and [PyTorch](http://pytorch.org/).\nReaders can be implemented using both. Input and output modules (i.e., pre- and post-processing) are independent of the\nML backend and can thus be reused for model modules that either backend.\nThough most models are implemented in TensorFlow by reusing the cumbersome pre- and post-processing it is easy to\nquickly build new readers in PyTorch as well.\n\n## Pre-trained Models\n\nFind pre-trained models [here](https://www.dropbox.com/sh/vnmc9pq4yrgl1sr/AAD7HVhGdpof2IgIifSZ6PEUa?dl=0).\n\n## Code Structure\n\n* `jack.core` - core abstractions used\n* `jack.readers` - implementations of models\n* `jack.eval` - task evaluation code\n* `jack.util` - utility code that is used throughout the framework, including shared ML code\n* `jack.io` - IO related code, including loading and dataset conversion scripts\n\n\n## Projects\n\n* [Integration of Knowledge into neural NLU systems](/projects/knowledge_integration)\n\n## Quickstart\n\n### Coding Tutorials - Notebooks \u0026 CLI\nWe provide ipython notebooks with tutorials on Jack. For the quickest start, you can begin [here][quickstart]. If you're interested in training a model yourself from code, see [this tutorial][model_training] (we recommend the command-line, see below), and if you'd like to implement a new model yourself, [this notebook][implementation] gives you a tutorial that explains this process in more detail.\n\nThere is documentation on our [command-line interface][cli] for actually **training and evaluating models**.\nFor a high-level explanation of the ideas and vision, see [Understanding Jack the Reader][understanding].\n\n[quickstart]: notebooks/quick_start.ipynb\n[model_training]: notebooks/model_training.ipynb\n[implementation]: notebooks/model_implementation.ipynb\n[install]: docs/How_to_install_and_run.md\n[api]: https://uclmr.github.io/jack/\n[notebooks]: notebooks/\n[understanding]: docs/Understanding_Jack_the_Reader.md\n[cli]: docs/CLI.md\n\n### Command-line Training and Usage of a QA System\nTo illustrate how jack works, we will show how to train a question answering\nmodel using our [command-line interface][cli] which is analoguous for other tasks (browse [conf/](./conf/) for existing task-dataset configurations).\nIt is probably best to setup a [virtual environment](https://docs.python.org/3/library/venv.html) to avoid\nclashes with system wide python library versions.\n\nFirst, install the framework:\n\n```bash\n$ python3 -m pip install -e .[tf]\n```\n\nThen, download the SQuAD dataset, and the GloVe word embeddings:\n\n```bash\n$ ./data/SQuAD/download.sh\n$ ./data/GloVe/download.sh\n```\n\nTrain a [FastQA][fastqa] model:\n\n```bash\n$ python3 bin/jack-train.py with train='data/SQuAD/train-v1.1.json' dev='data/SQuAD/dev-v1.1.json' reader='fastqa_reader' \\\n\u003e repr_dim=300 dropout=0.5 batch_size=64 seed=1337 loader='squad' save_dir='./fastqa_reader' epochs=20 \\\n\u003e with_char_embeddings=True embedding_format='memory_map_dir' embedding_file='data/GloVe/glove.840B.300d.memory_map_dir' vocab_from_embeddings=True\n```\n\nor shorter, using our prepared config:\n\n```bash\n$ python3 bin/jack-train.py with config='./conf/qa/squad/fastqa.yaml'\n```\n\nA copy of the model is written into the `save_dir` directory after each\ntraining epoch when performance improves. These can be loaded using the commands below or see e.g.\n[quickstart].\n\nYou want to train another model? No problem, we have a fairly modular QAModel implementation which allows you to stick\ntogether your own model. There are examples in `conf/qa/squad/` (e.g., `bidaf.yaml` or our own creation `jack_qa.yaml`).\nThese models are defined solely in the configs, i.e., there is not implementation in code.\nThis is possible through our `ModularQAModel`.\n\nIf all of that is too cumbersome for you and you just want to play, why not downloading a pretrained model:\n\n```bash\n$ # we still need GloVe in memory mapped format, ignore the next 2 commands if already downloaded and transformed\n$ data/GloVe/download.sh\n$ wget -O fastqa.zip https://www.dropbox.com/s/qb796uljoqj0lvo/fastqa.zip?dl=1\n$ unzip fastqa.zip \u0026\u0026 mv fastqa fastqa_reader\n```\n\n```python\nfrom jack import readers\nfrom jack.core import QASetting\n\nfastqa_reader = readers.reader_from_file(\"./fastqa_reader\")\n\nsupport = \"\"\"\"It is a replica of the grotto at Lourdes,\nFrance where the Virgin Mary reputedly appeared to Saint Bernadette Soubirous in 1858.\nAt the end of the main drive (and in a direct line that connects through 3 statues and the Gold Dome),\nis a simple, modern stone statue of Mary.\"\"\"\n\nanswers = fastqa_reader([QASetting(\n    question=\"To whom did the Virgin Mary allegedly appear in 1858 in Lourdes France?\",\n    support=[support]\n)])\n\nprint(answers[0][0].text)\n```\n[fastqa]: https://arxiv.org/abs/1703.04816\n[tf_summaries]: https://www.tensorflow.org/get_started/summaries_and_tensorboard\n[quick_start]: notebooks/quick_start.ipynb\n[cli]: docs/CLI.md\n\n## Support\nWe are thankful for support from:\n\n\u003ca href=\"http://mr.cs.ucl.ac.uk/\"\u003e\u003cimg src=\"http://mr.cs.ucl.ac.uk/images/uclmr_logo_round.png\" width=\"100px\"\u003e\u003c/a\u003e\n\u003ca href=\"http://www.softwarecampus.de/start/df\"\u003e\u003cimg src=\"https://idw-online.de/de/newsimage?id=186901\u0026size=screen\" width=\"100px\"\u003e\u003c/a\u003e\n\u003ca href=\"http://ec.europa.eu/research/mariecurieactions/funded-projects/career-integration-grants_en\"\u003e\u003cimg src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/8/84/European_Commission.svg/2000px-European_Commission.svg.png\" width=\"100px\"\u003e\u003c/a\u003e\n\n\u003ca href=\"http://bloomsbury.ai/\"\u003e\u003cimg src=\"https://www.dropbox.com/s/7hdb42azs03hbve/logo_text_square.png?raw=1\" width=\"100px\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.dfki.de/web\"\u003e\u003cimg src=\"https://www.dfki.de/web/presse/bildmaterial/dfki-logo-e-schrift.jpg\" width=\"100px\"\u003e\u003c/a\u003e\n\u003ca href=\"http://www.pgafamilyfoundation.org\"\u003e\u003cimg src=\"https://portlandmercado.files.wordpress.com/2013/02/pgaff_pms.jpg\" width=\"100px\"\u003e\u003c/a\u003e\n\u003ca href=\"http://summa-project.eu/\"\u003e\u003cimg src=\"http://summa-project.eu/wp-content/uploads/2017/04/summalogofinal.png\" width=\"100px\"\u003e\u003c/a\u003e\n\n## Developer guidelines\n\n- [Comply with the PEP 8 Style Guide][pep8]\n- Make sure all your code runs from the top level directory, e.g.:\n\n```shell\n$ pwd\n/home/pasquale/workspace/jack\n$ python3 bin/jack-train.py [..]\n```\n\n[pep8]: https://www.python.org/dev/peps/pep-0008/\n\n## Citing\n\n```\n@InProceedings{weissenborn2018jack,\nauthor    = {Dirk Weissenborn, Pasquale Minervini, Tim Dettmers, Isabelle Augenstein, Johannes Welbl, Tim Rocktäschel, Matko Bošnjak, Jeff Mitchell, Thomas Demeester, Pontus Stenetorp, Sebastian Riedel},\ntitle     = {{Jack the Reader – A Machine Reading Framework}},\nbooktitle = {{Proceedings of the 56th Annual Meeting of the Association for Computational Linguistics (ACL) System Demonstrations}},\nMonth     = {July},\nyear      = {2018},\nurl       = {https://arxiv.org/abs/1806.08727}\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuclnlp%2Fjack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuclnlp%2Fjack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuclnlp%2Fjack/lists"}