{"id":15064024,"url":"https://github.com/abductivelearning/ablkit","last_synced_at":"2025-05-12T13:23:00.004Z","repository":{"id":216049201,"uuid":"458693112","full_name":"AbductiveLearning/ABLkit","owner":"AbductiveLearning","description":"An efficient Python toolkit for Abductive Learning (ABL), a novel paradigm that integrates machine learning and logical reasoning in a unified framework.","archived":false,"fork":false,"pushed_at":"2024-09-12T06:16:54.000Z","size":9848,"stargazers_count":60,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-04T05:16:53.501Z","etag":null,"topics":["abductive-learning","machine-learning","neuro-symbolic","neuro-symbolic-learning","python","pytorch","sklearn"],"latest_commit_sha":null,"homepage":"https://ablkit.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AbductiveLearning.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":"2022-02-13T02:51:29.000Z","updated_at":"2025-04-25T14:47:03.000Z","dependencies_parsed_at":"2024-03-27T14:55:35.357Z","dependency_job_id":"4313f6c6-ff82-4eed-9072-e5725e166a72","html_url":"https://github.com/AbductiveLearning/ABLkit","commit_stats":null,"previous_names":["abductivelearning/ablkit"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbductiveLearning%2FABLkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbductiveLearning%2FABLkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbductiveLearning%2FABLkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbductiveLearning%2FABLkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AbductiveLearning","download_url":"https://codeload.github.com/AbductiveLearning/ABLkit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745361,"owners_count":21957356,"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":["abductive-learning","machine-learning","neuro-symbolic","neuro-symbolic-learning","python","pytorch","sklearn"],"created_at":"2024-09-25T00:10:21.880Z","updated_at":"2025-05-12T13:22:59.979Z","avatar_url":"https://github.com/AbductiveLearning.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/logo.png\" width=\"180\"\u003e\n\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ablkit)](https://pypi.org/project/ablkit/) [![PyPI version](https://badgen.net/pypi/v/ablkit)](https://pypi.org/project/ablkit/) [![Documentation Status](https://readthedocs.org/projects/ablkit/badge/?version=latest)](https://ablkit.readthedocs.io/en/latest/?badge=latest) [![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)](https://github.com/AbductiveLearning/ABLkit/blob/main/LICENSE) [![flake8 Lint](https://github.com/AbductiveLearning/ABLkit/actions/workflows/lint.yaml/badge.svg)](https://github.com/AbductiveLearning/ABLkit/actions/workflows/lint.yaml) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![ABLkit-CI](https://github.com/AbductiveLearning/ABLkit/actions/workflows/build-and-test.yaml/badge.svg)](https://github.com/AbductiveLearning/ABLkit/actions/workflows/build-and-test.yaml)\n\n[📘Documentation](https://ablkit.readthedocs.io/en/latest/index.html) | [📄Paper](https://journal.hep.com.cn/fcs/EN/10.1007/s11704-024-40085-7) | [📚Examples](https://github.com/AbductiveLearning/ABLkit/tree/main/examples) | [💬Reporting Issues](https://github.com/AbductiveLearning/ABLkit/issues/new)\n\n\u003c/div\u003e\n\n# ABLkit: A Toolkit for Abductive Learning\n\n**ABLkit** is an efficient Python toolkit for [**Abductive Learning (ABL)**](https://www.lamda.nju.edu.cn/publication/chap_ABL.pdf). ABL is a novel paradigm that integrates machine learning and logical reasoning in a unified framework. It is suitable for tasks where both data and (logical) domain knowledge are available. \n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/ABL.png\" alt=\"Abductive Learning\" style=\"width: 80%;\"/\u003e\n\u003c/p\u003e\n\nKey Features of ABLkit:\n\n- **High Flexibility**: Compatible with various machine learning modules and logical reasoning components.\n- **Easy-to-Use Interface**: Provide data, model, and knowledge, and get started with just a few lines of code.\n- **Optimized Performance**: Optimization for high performance and accelerated training speed.\n\nABLkit encapsulates advanced ABL techniques, providing users with an efficient and convenient toolkit to develop dual-driven ABL systems, which leverage the power of both data and knowledge.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/ABLkit.png\" alt=\"ABLkit\" style=\"width: 80%;\"/\u003e\n\u003c/p\u003e\n\n## Installation\n\n### Install from PyPI\n\nThe easiest way to install ABLkit is using ``pip``:\n\n```bash\npip install ablkit\n```\n\n### Install from Source\n\nAlternatively, to install from source code, sequentially run following commands in your terminal/command line.\n\n```bash\ngit clone https://github.com/AbductiveLearning/ABLkit.git\ncd ABLkit\npip install -v -e .\n```\n\n### (Optional) Install SWI-Prolog\n\nIf the use of a [Prolog-based knowledge base](https://ablkit.readthedocs.io/en/latest/Intro/Reasoning.html#prolog) is necessary, please also install [SWI-Prolog](https://www.swi-prolog.org/):\n\nFor Linux users:\n\n```bash\nsudo apt-get install swi-prolog\n```\n\nFor Windows and Mac users, please refer to the [SWI-Prolog Install Guide](https://github.com/yuce/pyswip/blob/master/INSTALL.md).\n\n## Quick Start\n\nWe use the MNIST Addition task as a quick start example. In this task, pairs of MNIST handwritten images and their sums are given, alongwith a domain knowledge base which contains information on how to perform addition operations. Our objective is to input a pair of handwritten images and accurately determine their sum.\n\n\u003cdetails\u003e\n\u003csummary\u003eWorking with Data\u003c/summary\u003e\n\u003cbr\u003e\n\nABLkit requires data in the format of `(X, gt_pseudo_label, Y)` where `X` is a list of input examples containing instances, `gt_pseudo_label` is the ground-truth label of each example in `X` and `Y` is the ground-truth reasoning result of each example in `X`. Note that `gt_pseudo_label` is only used to evaluate the machine learning model's performance but not to train it. \n\nIn the MNIST Addition task, the data loading looks like:\n\n```python\n# The 'datasets' module below is located in 'examples/mnist_add/'\nfrom datasets import get_dataset\n    \n# train_data and test_data are tuples in the format of (X, gt_pseudo_label, Y)\ntrain_data = get_dataset(train=True)\ntest_data = get_dataset(train=False)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuilding the Learning Part\u003c/summary\u003e\n\u003cbr\u003e\n\nLearning part is constructed by first defining a base model for machine learning. ABLkit offers considerable flexibility, supporting any base model that conforms to the scikit-learn style (which requires the implementation of `fit` and `predict` methods), or a PyTorch-based neural network (which has defined the architecture and implemented `forward` method). In this example, we build a simple LeNet5 network as the base model.\n\n```python\n# The 'models' module below is located in 'examples/mnist_add/'\nfrom models.nn import LeNet5\n\ncls = LeNet5(num_classes=10)\n``` \n\nTo facilitate uniform processing, ABLkit provides the `BasicNN` class to convert a PyTorch-based neural network into a format compatible with scikit-learn models. To construct a `BasicNN` instance, aside from the network itself, we also need to define a loss function, an optimizer, and the computing device.\n\n```python\n​import torch\n​from ablkit.learning import BasicNN\n​    \n​loss_fn = torch.nn.CrossEntropyLoss()\n​optimizer = torch.optim.RMSprop(cls.parameters(), lr=0.001, alpha=0.9)\n​device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n​base_model = BasicNN(model=cls, loss_fn=loss_fn, optimizer=optimizer, device=device)\n```\n\nThe base model built above is trained to make predictions on instance-level data (e.g., a single image), while ABL deals with example-level data. To bridge this gap, we wrap the `base_model` into an instance of `ABLModel`. This class serves as a unified wrapper for base models, facilitating the learning part to train, test, and predict on example-level data, (e.g., images that comprise an equation).\n\n```python\nfrom ablkit.learning import ABLModel\n​    \n​model = ABLModel(base_model)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuilding the Reasoning Part\u003c/summary\u003e\n\u003cbr\u003e\n\nTo build the reasoning part, we first define a knowledge base by creating a subclass of `KBBase`. In the subclass, we initialize the `pseudo_label_list` parameter and override the `logic_forward` method, which specifies how to perform (deductive) reasoning that processes pseudo-labels of an example to the corresponding reasoning result. Specifically, for the MNIST Addition task, this `logic_forward` method is tailored to execute the sum operation.\n\n```python\nfrom ablkit.reasoning import KBBase\n​    \nclass AddKB(KBBase):\n    def __init__(self, pseudo_label_list=list(range(10))):\n        super().__init__(pseudo_label_list)\n\n​    def logic_forward(self, nums):\n        return sum(nums)\n​    \nkb = AddKB()\n```\n\nNext, we create a reasoner by instantiating the class `Reasoner`, passing the knowledge base as a parameter. Due to the indeterminism of abductive reasoning, there could be multiple candidate pseudo-labels compatible to the knowledge base. In such scenarios, the reasoner can minimize inconsistency and return the pseudo-label with the highest consistency.\n\n```python\nfrom ablkit.reasoning import Reasoner\n​    \nreasoner = Reasoner(kb)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuilding Evaluation Metrics\u003c/summary\u003e\n\u003cbr\u003e\n\nABLkit provides two basic metrics, namely `SymbolAccuracy` and `ReasoningMetric`, which are used to evaluate the accuracy of the machine learning model's predictions and the accuracy of the `logic_forward` results, respectively.\n\n```python\nfrom ablkit.data.evaluation import ReasoningMetric, SymbolAccuracy\n​    \nmetric_list = [SymbolAccuracy(), ReasoningMetric(kb=kb)]\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBridging Learning and Reasoning\u003c/summary\u003e\n\u003cbr\u003e\n\nNow, we use `SimpleBridge` to combine learning and reasoning in a unified ABL framework.\n\n```python\nfrom ablkit.bridge import SimpleBridge\n​    \nbridge = SimpleBridge(model, reasoner, metric_list)\n```\n\nFinally, we proceed with training and testing.\n\n```python\n​bridge.train(train_data, loops=1, segment_size=0.01)\nbridge.test(test_data)\n```\n\n\u003c/details\u003e\n\nTo explore detailed tutorials and information, please refer to: [Documentation on Read the Docs](https://ablkit.readthedocs.io/en/latest/index.html).\n\n## Examples\n\nWe provide several examples in `examples/`. Each example is stored in a separate folder containing a README file.\n\n+ [MNIST Addition](https://github.com/AbductiveLearning/ABLkit/tree/main/examples/mnist_add)\n+ [Handwritten Formula (HWF)](https://github.com/AbductiveLearning/ABLkit/tree/main/examples/hwf)\n+ [Handwritten Equation Decipherment](https://github.com/AbductiveLearning/ABLkit/tree/main/examples/hed)\n+ [Zoo](https://github.com/AbductiveLearning/ABLkit/tree/main/examples/zoo)\n\n## References\n\nFor more information about ABL, please refer to: [Zhou, 2019](http://scis.scichina.com/en/2019/076101.pdf) and [Zhou and Huang, 2022](https://www.lamda.nju.edu.cn/publication/chap_ABL.pdf).\n\n```\n@article{zhou2019abductive,\n  title     = {Abductive learning: towards bridging machine learning and logical reasoning},\n  author    = {Zhou, Zhi-Hua},\n  journal   = {Science China Information Sciences},\n  volume    = {62},\n  number    = {7},\n  pages     = {76101},\n  year      = {2019}\n}\n\n@incollection{zhou2022abductive,\n  title     = {Abductive Learning},\n  author    = {Zhou, Zhi-Hua and Huang, Yu-Xuan},\n  booktitle = {Neuro-Symbolic Artificial Intelligence: The State of the Art},\n  editor    = {Pascal Hitzler and Md. Kamruzzaman Sarker},\n  publisher = {{IOS} Press},\n  pages     = {353--369},\n  address   = {Amsterdam},\n  year      = {2022}\n}\n```\n\n## Citation\n\nTo cite ABLkit, please cite the following paper:  [Huang et al., 2024](https://journal.hep.com.cn/fcs/EN/10.1007/s11704-024-40085-7).\n\n```\n@article{ABLkit2024,\n  author     = {Huang, Yu-Xuan and Hu, Wen-Chao and Gao, En-Hao and Jiang, Yuan},\n  title      = {ABLkit: a Python toolkit for abductive learning},\n  journal    = {Frontiers of Computer Science},\n  volume     = {18},\n  number     = {6},\n  pages      = {186354},\n  year       = {2024}\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabductivelearning%2Fablkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabductivelearning%2Fablkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabductivelearning%2Fablkit/lists"}