<div align="center">
<img src="https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/logo.png" width="180">
[](https://pypi.org/project/ablkit/) [](https://pypi.org/project/ablkit/) [](https://ablkit.readthedocs.io/en/latest/?badge=latest) [](https://github.com/AbductiveLearning/ABLkit/blob/main/LICENSE) [](https://github.com/AbductiveLearning/ABLkit/actions/workflows/lint.yaml) [](https://github.com/psf/black) [](https://github.com/AbductiveLearning/ABLkit/actions/workflows/build-and-test.yaml)
[📘Documentation](https://ablkit.readthedocs.io/en/latest/index.html) | [📚Examples](https://github.com/AbductiveLearning/ABLkit/tree/main/examples) | [💬Reporting Issues](https://github.com/AbductiveLearning/ABLkit/issues/new)
</div>
# ABLkit: A Toolkit for Abductive Learning
**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.
<p align="center">
<img src="https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/ABL.png" alt="Abductive Learning" style="width: 80%;"/>
</p>
Key Features of ABLkit:
- **High Flexibility**: Compatible with various machine learning modules and logical reasoning components.
- **User-Friendly Interface**: Provide data, model, and knowledge, and get started with just a few lines of code.
- **Optimized Performance**: Optimization for high performance and accelerated training speed.
ABLkit 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.
<p align="center">
<img src="https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/ABLkit.png" alt="ABLkit" style="width: 80%;"/>
</p>
## Installation
### Install from PyPI
The easiest way to install ABLkit is using ``pip``:
```bash
pip install ablkit
```
### Install from Source
Alternatively, to install from source code, sequentially run following commands in your terminal/command line.
```bash
git clone https://github.com/AbductiveLearning/ABLkit.git
cd ABLkit
pip install -v -e .
```
### (Optional) Install SWI-Prolog
If 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/):
For Linux users:
```bash
sudo apt-get install swi-prolog
```
For Windows and Mac users, please refer to the [SWI-Prolog Install Guide](https://github.com/yuce/pyswip/blob/master/INSTALL.md).
## Quick Start
We 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.
<details>
<summary>Working with Data</summary>
<br>
ABLkit 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.
In the MNIST Addition task, the data loading looks like:
```python
# The 'datasets' module below is located in 'examples/mnist_add/'
from datasets import get_dataset
# train_data and test_data are tuples in the format of (X, gt_pseudo_label, Y)
train_data = get_dataset(train=True)
test_data = get_dataset(train=False)
```
</details>
<details>
<summary>Building the Learning Part</summary>
<br>
Learning 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.
```python
# The 'models' module below is located in 'examples/mnist_add/'
from models.nn import LeNet5
cls = LeNet5(num_classes=10)
```
To 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.
```python
​import torch
​from ablkit.learning import BasicNN
​
​loss_fn = torch.nn.CrossEntropyLoss()
​optimizer = torch.optim.RMSprop(cls.parameters(), lr=0.001, alpha=0.9)
​device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
​base_model = BasicNN(model=cls, loss_fn=loss_fn, optimizer=optimizer, device=device)
```
The 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).
```python
from ablkit.learning import ABLModel
​
​model = ABLModel(base_model)
```
</details>
<details>
<summary>Building the Reasoning Part</summary>
<br>
To 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.
```python
from ablkit.reasoning import KBBase
​
class AddKB(KBBase):
def __init__(self, pseudo_label_list=list(range(10))):
super().__init__(pseudo_label_list)
​ def logic_forward(self, nums):
return sum(nums)
​
kb = AddKB()
```
Next, 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.
```python
from ablkit.reasoning import Reasoner
​
reasoner = Reasoner(kb)
```
</details>
<details>
<summary>Building Evaluation Metrics</summary>
<br>
ABLkit 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.
```python
from ablkit.data.evaluation import ReasoningMetric, SymbolAccuracy
​
metric_list = [SymbolAccuracy(), ReasoningMetric(kb=kb)]
```
</details>
<details>
<summary>Bridging Learning and Reasoning</summary>
<br>
Now, we use `SimpleBridge` to combine learning and reasoning in a unified ABL framework.
```python
from ablkit.bridge import SimpleBridge
​
bridge = SimpleBridge(model, reasoner, metric_list)
```
Finally, we proceed with training and testing.
```python
​bridge.train(train_data, loops=1, segment_size=0.01)
bridge.test(test_data)
```
</details>
To explore detailed tutorials and information, please refer to - [document](https://ablkit.readthedocs.io/en/latest/index.html).
## Examples
We provide several examples in `examples/`. Each example is stored in a separate folder containing a README file.
+ [MNIST Addition](https://github.com/AbductiveLearning/ABLkit/tree/main/examples/mnist_add)
+ [Handwritten Formula (HWF)](https://github.com/AbductiveLearning/ABLkit/tree/main/examples/hwf)
+ [Handwritten Equation Decipherment](https://github.com/AbductiveLearning/ABLkit/tree/main/examples/hed)
+ [Zoo](https://github.com/AbductiveLearning/ABLkit/tree/main/examples/zoo)
## References
For 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).
```
@article{zhou2019abductive,
title = {Abductive learning: towards bridging machine learning and logical reasoning},
author = {Zhou, Zhi-Hua},
journal = {Science China Information Sciences},
volume = {62},
number = {7},
pages = {76101},
year = {2019}
}
@incollection{zhou2022abductive,
title = {Abductive Learning},
author = {Zhou, Zhi-Hua and Huang, Yu-Xuan},
booktitle = {Neuro-Symbolic Artificial Intelligence: The State of the Art},
editor = {Pascal Hitzler and Md. Kamruzzaman Sarker},
publisher = {{IOS} Press},
pages = {353--369},
address = {Amsterdam},
year = {2022}
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "ablkit",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.0",
"maintainer_email": "",
"keywords": "machine-learning,framework,abductive-learning,neuro-symbolic",
"author": "",
"author_email": "LAMDA 2024 <abductivelearning@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1a/8e/1cff36703ebc0e470d19300bfff6db7a7a0c5643fb36afc636214c4fe284/ablkit-0.2.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/logo.png\" width=\"180\">\n\n[](https://pypi.org/project/ablkit/) [](https://pypi.org/project/ablkit/) [](https://ablkit.readthedocs.io/en/latest/?badge=latest) [](https://github.com/AbductiveLearning/ABLkit/blob/main/LICENSE) [](https://github.com/AbductiveLearning/ABLkit/actions/workflows/lint.yaml) [](https://github.com/psf/black) [](https://github.com/AbductiveLearning/ABLkit/actions/workflows/build-and-test.yaml)\n\n[\ud83d\udcd8Documentation](https://ablkit.readthedocs.io/en/latest/index.html) | [\ud83d\udcdaExamples](https://github.com/AbductiveLearning/ABLkit/tree/main/examples) | [\ud83d\udcacReporting Issues](https://github.com/AbductiveLearning/ABLkit/issues/new)\n\n</div>\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<p align=\"center\">\n<img src=\"https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/ABL.png\" alt=\"Abductive Learning\" style=\"width: 80%;\"/>\n</p>\n\nKey Features of ABLkit:\n\n- **High Flexibility**: Compatible with various machine learning modules and logical reasoning components.\n- **User-Friendly 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<p align=\"center\">\n<img src=\"https://raw.githubusercontent.com/AbductiveLearning/ABLkit/main/docs/_static/img/ABLkit.png\" alt=\"ABLkit\" style=\"width: 80%;\"/>\n</p>\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<details>\n<summary>Working with Data</summary>\n<br>\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</details>\n\n<details>\n<summary>Building the Learning Part</summary>\n<br>\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\u200bimport torch\n\u200bfrom ablkit.learning import BasicNN\n\u200b \n\u200bloss_fn = torch.nn.CrossEntropyLoss()\n\u200boptimizer = torch.optim.RMSprop(cls.parameters(), lr=0.001, alpha=0.9)\n\u200bdevice = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n\u200bbase_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\u200b \n\u200bmodel = ABLModel(base_model)\n```\n\n</details>\n\n<details>\n<summary>Building the Reasoning Part</summary>\n<br>\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\u200b \nclass AddKB(KBBase):\n def __init__(self, pseudo_label_list=list(range(10))):\n super().__init__(pseudo_label_list)\n\n\u200b def logic_forward(self, nums):\n return sum(nums)\n\u200b \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\u200b \nreasoner = Reasoner(kb)\n```\n\n</details>\n\n<details>\n<summary>Building Evaluation Metrics</summary>\n<br>\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\u200b \nmetric_list = [SymbolAccuracy(), ReasoningMetric(kb=kb)]\n```\n\n</details>\n\n<details>\n<summary>Bridging Learning and Reasoning</summary>\n<br>\n\nNow, we use `SimpleBridge` to combine learning and reasoning in a unified ABL framework.\n\n```python\nfrom ablkit.bridge import SimpleBridge\n\u200b \nbridge = SimpleBridge(model, reasoner, metric_list)\n```\n\nFinally, we proceed with training and testing.\n\n```python\n\u200bbridge.train(train_data, loops=1, segment_size=0.01)\nbridge.test(test_data)\n```\n\n</details>\n\nTo explore detailed tutorials and information, please refer to - [document](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",
"bugtrack_url": null,
"license": "MIT LICENSE",
"summary": "Abductive Learning (ABL) toolkit",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/AbductiveLearning/ABLkit",
"Issues": "https://github.com/AbductiveLearning/ABLkit/issues"
},
"split_keywords": [
"machine-learning",
"framework",
"abductive-learning",
"neuro-symbolic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "104c1cec12cf2dd5d785d5a0ecbf148d29ecc897408e46185a3380e8e3fceef5",
"md5": "451b500b47fd0ba3dfcd6c387e4b2d07",
"sha256": "2fe28b59d14ad2b967c8844bd22eff03bbbe6f162463bdc4feba09fe06c70679"
},
"downloads": -1,
"filename": "ablkit-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "451b500b47fd0ba3dfcd6c387e4b2d07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.0",
"size": 61234,
"upload_time": "2024-01-24T02:52:38",
"upload_time_iso_8601": "2024-01-24T02:52:38.524496Z",
"url": "https://files.pythonhosted.org/packages/10/4c/1cec12cf2dd5d785d5a0ecbf148d29ecc897408e46185a3380e8e3fceef5/ablkit-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1a8e1cff36703ebc0e470d19300bfff6db7a7a0c5643fb36afc636214c4fe284",
"md5": "fce5b2267321f0fff83a05a77ee62b1b",
"sha256": "9edfdecbff501f1f6336ae081f0ec9c733743c88070895ebd1fd919736a47a3c"
},
"downloads": -1,
"filename": "ablkit-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "fce5b2267321f0fff83a05a77ee62b1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.0",
"size": 57047,
"upload_time": "2024-01-24T02:52:40",
"upload_time_iso_8601": "2024-01-24T02:52:40.630271Z",
"url": "https://files.pythonhosted.org/packages/1a/8e/1cff36703ebc0e470d19300bfff6db7a7a0c5643fb36afc636214c4fe284/ablkit-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-24 02:52:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AbductiveLearning",
"github_project": "ABLkit",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "ablkit"
}
JSON
