<h1 align="center"> PSyKI </h1>
<h2 align="center">Platform for Symbolic Knowledge Injection</h2>
[](https://badge.fury.io/py/psyki)
[]()
[]()
[](https://github.com/psf/black)
[](https://opensource.org/licenses/Apache-2.0)
[](https://stand-with-ukraine.pp.ua)
Some quick links:
<!-- * [Home Page](https://apice.unibo.it/xwiki/bin/view/PSyKI/) -->
* [GitHub Repository](https://github.com/psykei/psyki-python)
* [PyPi Repository](https://pypi.org/project/psyki/)
* [Issues](https://github.com/psykei/psyki-python/issues)
### Reference paper
> Matteo Magnini, Giovanni Ciatto, Andrea Omicini. "[On the Design of PSyKI: A Platform for Symbolic Knowledge Injection into Sub-Symbolic Predictors]", in: Proceedings of the 4th International Workshop on EXplainable and TRAnsparent AI and Multi-Agent Systems, 2022.
Bibtex:
```bibtex
@inproceedings{PsykiExtraamas2022,
keywords = {Symbolic Knowledge Injection, Explainable AI, XAI, Neural Networks, PSyKI},
year = 2022,
talk = {Talks.PsykiExtraamas2022},
author = {Magnini, Matteo and Ciatto, Giovanni and Omicini, Andrea},
venue_e = {Events.Extraamas2022},
sort = {inproceedings},
publisher = {Springer},
status = {In press},
title = {On the Design of PSyKI: a Platform for Symbolic Knowledge Injection into Sub-Symbolic Predictors},
booktitle = {Proceedings of the 4th International Workshop on EXplainable and TRAnsparent AI and Multi-Agent Systems}
}
```
## Intro
PSyKI (Platform for Symbolic Knowledge Injection) is a python library for **symbolic knowledge injection** (SKI).
In the literature, SKI may also be referred as **neuro-symbolic integration**.
PSyKI offers SKI algorithms (**injectors**) along with quality of service metrics (QoS) and other utility functionalities.
Finally, the library is open to extendability.
### More in detail
An `Injector` is a SKI algorithm that may -- or may not -- take a sub-symbolic predictor in conjunction with prior symbolic knowledge to create a new predictor through the `inject` method.
We refer to the new predictor as **educated**, while predictors that are not affected by symbolic knowledge are called **uneducated**.
Knowledge can be represented in many ways.
The most common is the representation via logic formulae.
PSyKI integrates [`2ppy`](https://github.com/tuProlog/2ppy), a python porting of [`2p-kt`](https://github.com/tuProlog/2p-kt) (a multi-paradigm logic programming framework).
Thanks to this integration, PSyKI supports logic formulae written with the formalism of Prolog.
Therefore, all subsets of the Prolog language (including Prolog itself) are potentially supported (e.g., propositional logic, Datalog, etc.).
It is worth noting that each injector may have its own requirements on the knowledge representation.
List of available injectors:
- [`KBANN`](https://www.sciencedirect.com/science/article/pii/0004370294901058), one of the first injector introduced in literature;
- [`KILL`](http://ceur-ws.org/Vol-3261/paper5.pdf), constrains a NN by altering its predictions using the knowledge;
- [`KINS`](http://ceur-ws.org/Vol-3204/paper_25.pdf), structure the knowledge adding ad-hoc layers into a NN.
### High level architecture
*Class diagram representing the relations between `Injector`, `Theory` and `Fuzzifier` classes*
<!--
To generate/edit the class diagram browse the URL above, after replacing `svg` with `uml`
-->
The core abstractions of PSyKI are the following:
- `Injector`: a SKI algorithm;
- `Theory`: symbolic knowledge plus additional information about the domain;
- `Fuzzifier`: entity that transforms (fuzzify) symbolic knowledge into a sub-symbolic data structure.
The class `Theory` is built upon the symbolic knowledge and the metadata of the dataset (extracted by a Pandas DataFrame).
The knowledge can be generated by an adapter that parses the Prolog theory (e.g., a `.pl` file, a string) and generates a list of `Formula` objects.
Each `Injector` has one `Fuzzifier`.
The `Fuzzifier` is used to transform the `Theory` into a sub-symbolic data structure (e.g., ad-hoc layers of a NN).
Different fuzzifiers encode the knowledge in different ways.
To avoid confusion, we use the following terminology:
- **rule** is a single logic clause;
- **knowledge** is the set of rules;
- **theory** is the knowledge plus metadata.
### Hello world
The following example shows how to use PSyKI to inject knowledge into a NN.
```python
import pandas as pd
from tensorflow.keras.models import Model
from psyki.logic import Theory
from psyki.ski import Injector
def create_uneducated_predictor() -> Model:
...
dataset = pd.read_csv("path_to_dataset.csv") # load dataset
knowledge_file = "path_to_knowledge_file.pl" # load knowledge
theory = Theory(knowledge_file, dataset) # create a theory
uneducated = create_uneducated_predictor() # create a NN
injector = Injector.kins(uneducated) # create an injector
educated = injector.inject(theory) # inject knowledge into the NN
# From now on you can use the educated predictor as you would use the uneducated one
```
For more detailed examples, please refer to the demos in the [demo-psyki-python](https://github.com/psykei/demo-psyki-python) repository.
## Users
PSyKI is deployed as a library on Pypi, and it can therefore be installed as Python package by running:
```text
pip install psyki
```
### Requirements
- python 3.9+
- java 11
- 2ppy 0.4.0
- tensorflow 2.7.0
- numpy 1.22.3
- scikit-learn 1.0.2
- pandas 1.4.2
- codecarbon 2.1.4
## Developers
Working with PSyKI codebase requires a number of tools to be installed:
* Python 3.9+
* JDK 11+ (please ensure the `JAVA_HOME` environment variable is properly configured)
* Git 2.20+
### Develop PSyKI with PyCharm
To participate in the development of PSyKI, we suggest the [PyCharm](https://www.jetbrains.com/pycharm/) IDE.
#### Importing the project
1. Clone this repository in a folder of your preference using `git_clone` appropriately
2. Open PyCharm
3. Select `Open`
4. Navigate your file system and find the folder where you cloned the repository
5. Click `Open`
### Developing the project
Contributions to this project are welcome. Just some rules:
* We use [git flow](https://github.com/nvie/gitflow), so if you write new features, please do so in a separate `feature/` branch
* We recommend forking the project, developing your stuff, then contributing back vie pull request
* Commit often
* Stay in sync with the `develop` (or `main | master`) branch (pull frequently if the build passes)
* Do not introduce low quality or untested code
#### Issue tracking
If you meet some problem in using or developing PSyKI, you are encouraged to signal it through the project
["Issues" section](https://github.com/psykei/psyki-python/issues) on GitHub.
Raw data
{
"_id": null,
"home_page": "https://github.com/psykei/psyki-python",
"name": "psyki",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9.0, <3.10",
"maintainer_email": "",
"keywords": "symbolic knowledge injection,ski,symbolic ai",
"author": "Matteo Magnini",
"author_email": "matteo.magnini@unibo.it",
"download_url": "https://files.pythonhosted.org/packages/fe/70/98c5fa88873dcfe140b63599d493e8b9982f91ff9b19f327351ee37504be/psyki-0.3.12.tar.gz",
"platform": "Independant",
"description": "<h1 align=\"center\"> PSyKI </h1>\n<h2 align=\"center\">Platform for Symbolic Knowledge Injection</h2>\n\n[](https://badge.fury.io/py/psyki)\n[]()\n\n[]()\n[](https://github.com/psf/black)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://stand-with-ukraine.pp.ua)\n\nSome quick links:\n<!-- * [Home Page](https://apice.unibo.it/xwiki/bin/view/PSyKI/) -->\n* [GitHub Repository](https://github.com/psykei/psyki-python)\n* [PyPi Repository](https://pypi.org/project/psyki/)\n* [Issues](https://github.com/psykei/psyki-python/issues)\n\n### Reference paper\n\n> Matteo Magnini, Giovanni Ciatto, Andrea Omicini. \"[On the Design of PSyKI: A Platform for Symbolic Knowledge Injection into Sub-Symbolic Predictors]\", in: Proceedings of the 4th International Workshop on EXplainable and TRAnsparent AI and Multi-Agent Systems, 2022.\n\nBibtex: \n```bibtex\n@inproceedings{PsykiExtraamas2022,\n\tkeywords = {Symbolic Knowledge Injection, Explainable AI, XAI, Neural Networks, PSyKI},\n\tyear = 2022,\n\ttalk = {Talks.PsykiExtraamas2022},\n\tauthor = {Magnini, Matteo and Ciatto, Giovanni and Omicini, Andrea},\n\tvenue_e = {Events.Extraamas2022},\n\tsort = {inproceedings},\n\tpublisher = {Springer},\n\tstatus = {In press},\n\ttitle = {On the Design of PSyKI: a Platform for Symbolic Knowledge Injection into Sub-Symbolic Predictors},\n\tbooktitle = {Proceedings of the 4th International Workshop on EXplainable and TRAnsparent AI and Multi-Agent Systems}\n}\n```\n\n## Intro\n\nPSyKI (Platform for Symbolic Knowledge Injection) is a python library for **symbolic knowledge injection** (SKI).\nIn the literature, SKI may also be referred as **neuro-symbolic integration**.\nPSyKI offers SKI algorithms (**injectors**) along with quality of service metrics (QoS) and other utility functionalities.\nFinally, the library is open to extendability.\n\n### More in detail\n\nAn `Injector` is a SKI algorithm that may -- or may not -- take a sub-symbolic predictor in conjunction with prior symbolic knowledge to create a new predictor through the `inject` method.\nWe refer to the new predictor as **educated**, while predictors that are not affected by symbolic knowledge are called **uneducated**.\n\nKnowledge can be represented in many ways.\nThe most common is the representation via logic formulae.\nPSyKI integrates [`2ppy`](https://github.com/tuProlog/2ppy), a python porting of [`2p-kt`](https://github.com/tuProlog/2p-kt) (a multi-paradigm logic programming framework).\nThanks to this integration, PSyKI supports logic formulae written with the formalism of Prolog.\nTherefore, all subsets of the Prolog language (including Prolog itself) are potentially supported (e.g., propositional logic, Datalog, etc.).\nIt is worth noting that each injector may have its own requirements on the knowledge representation.\n\nList of available injectors:\n\n - [`KBANN`](https://www.sciencedirect.com/science/article/pii/0004370294901058), one of the first injector introduced in literature;\n - [`KILL`](http://ceur-ws.org/Vol-3261/paper5.pdf), constrains a NN by altering its predictions using the knowledge;\n - [`KINS`](http://ceur-ws.org/Vol-3204/paper_25.pdf), structure the knowledge adding ad-hoc layers into a NN.\n\n### High level architecture\n\n\n*Class diagram representing the relations between `Injector`, `Theory` and `Fuzzifier` classes*\n\n<!--\nTo generate/edit the class diagram browse the URL above, after replacing `svg` with `uml`\n-->\n\nThe core abstractions of PSyKI are the following:\n\n - `Injector`: a SKI algorithm;\n - `Theory`: symbolic knowledge plus additional information about the domain;\n - `Fuzzifier`: entity that transforms (fuzzify) symbolic knowledge into a sub-symbolic data structure.\n\nThe class `Theory` is built upon the symbolic knowledge and the metadata of the dataset (extracted by a Pandas DataFrame).\nThe knowledge can be generated by an adapter that parses the Prolog theory (e.g., a `.pl` file, a string) and generates a list of `Formula` objects.\nEach `Injector` has one `Fuzzifier`.\nThe `Fuzzifier` is used to transform the `Theory` into a sub-symbolic data structure (e.g., ad-hoc layers of a NN).\nDifferent fuzzifiers encode the knowledge in different ways.\n\nTo avoid confusion, we use the following terminology:\n\n - **rule** is a single logic clause;\n - **knowledge** is the set of rules;\n - **theory** is the knowledge plus metadata.\n\n### Hello world\n\nThe following example shows how to use PSyKI to inject knowledge into a NN.\n\n```python\nimport pandas as pd\nfrom tensorflow.keras.models import Model\nfrom psyki.logic import Theory\nfrom psyki.ski import Injector\n\n\ndef create_uneducated_predictor() -> Model:\n...\n\ndataset = pd.read_csv(\"path_to_dataset.csv\") # load dataset\nknowledge_file = \"path_to_knowledge_file.pl\" # load knowledge\ntheory = Theory(knowledge_file, dataset) # create a theory\nuneducated = create_uneducated_predictor() # create a NN\ninjector = Injector.kins(uneducated) # create an injector\neducated = injector.inject(theory) # inject knowledge into the NN\n\n# From now on you can use the educated predictor as you would use the uneducated one\n```\n\nFor more detailed examples, please refer to the demos in the [demo-psyki-python](https://github.com/psykei/demo-psyki-python) repository.\n\n## Users\n\nPSyKI is deployed as a library on Pypi, and it can therefore be installed as Python package by running:\n```text\npip install psyki\n```\n\n### Requirements\n\n- python 3.9+\n- java 11\n- 2ppy 0.4.0\n- tensorflow 2.7.0\n- numpy 1.22.3\n- scikit-learn 1.0.2\n- pandas 1.4.2\n- codecarbon 2.1.4\n\n\n## Developers\n\nWorking with PSyKI codebase requires a number of tools to be installed:\n* Python 3.9+\n* JDK 11+ (please ensure the `JAVA_HOME` environment variable is properly configured)\n* Git 2.20+\n\n### Develop PSyKI with PyCharm\n\nTo participate in the development of PSyKI, we suggest the [PyCharm](https://www.jetbrains.com/pycharm/) IDE.\n\n#### Importing the project\n\n1. Clone this repository in a folder of your preference using `git_clone` appropriately\n2. Open PyCharm\n3. Select `Open`\n4. Navigate your file system and find the folder where you cloned the repository\n5. Click `Open`\n\n### Developing the project\n\nContributions to this project are welcome. Just some rules:\n* We use [git flow](https://github.com/nvie/gitflow), so if you write new features, please do so in a separate `feature/` branch\n* We recommend forking the project, developing your stuff, then contributing back vie pull request\n* Commit often\n* Stay in sync with the `develop` (or `main | master`) branch (pull frequently if the build passes)\n* Do not introduce low quality or untested code\n\n#### Issue tracking\nIf you meet some problem in using or developing PSyKI, you are encouraged to signal it through the project\n[\"Issues\" section](https://github.com/psykei/psyki-python/issues) on GitHub.\n\n",
"bugtrack_url": null,
"license": "Apache 2.0 License",
"summary": "Python-based implementation of PSyKI, i.e. a Platform for Symbolic Knowledge Injection",
"version": "0.3.12",
"project_urls": {
"Bug Reports": "https://github.com/psykei/psyki-python/issues",
"Homepage": "https://github.com/psykei/psyki-python",
"Source": "https://github.com/psykei/psyki-python"
},
"split_keywords": [
"symbolic knowledge injection",
"ski",
"symbolic ai"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "52e9ffc8f076f1385f01227656ca5051043a2dc9c39a3f19d3cd3bc923e70944",
"md5": "e85da5272b766c35231a0a443ad74ac9",
"sha256": "803fcb41d1ad26e285dcbcaabf7e20c0fa338f9ae66b16849c5d2a6c2c85bfb3"
},
"downloads": -1,
"filename": "psyki-0.3.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e85da5272b766c35231a0a443ad74ac9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0, <3.10",
"size": 40381,
"upload_time": "2023-05-26T12:51:15",
"upload_time_iso_8601": "2023-05-26T12:51:15.137033Z",
"url": "https://files.pythonhosted.org/packages/52/e9/ffc8f076f1385f01227656ca5051043a2dc9c39a3f19d3cd3bc923e70944/psyki-0.3.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fe7098c5fa88873dcfe140b63599d493e8b9982f91ff9b19f327351ee37504be",
"md5": "23098478e66f89026862b6833d58c681",
"sha256": "a54b3fc0258bc2c5fe53c23d849a76eb542a78764ae465fd6ce7a3fd597d6739"
},
"downloads": -1,
"filename": "psyki-0.3.12.tar.gz",
"has_sig": false,
"md5_digest": "23098478e66f89026862b6833d58c681",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0, <3.10",
"size": 44752,
"upload_time": "2023-05-26T12:51:17",
"upload_time_iso_8601": "2023-05-26T12:51:17.102354Z",
"url": "https://files.pythonhosted.org/packages/fe/70/98c5fa88873dcfe140b63599d493e8b9982f91ff9b19f327351ee37504be/psyki-0.3.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-26 12:51:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "psykei",
"github_project": "psyki-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "build",
"specs": [
[
">=",
"0.6.0"
]
]
},
{
"name": "twine",
"specs": [
[
">=",
"3.4.2"
]
]
},
{
"name": "2ppy",
"specs": [
[
">=",
"0.4.0"
]
]
},
{
"name": "tensorflow",
"specs": [
[
"<",
"2.12.0"
],
[
">=",
"2.7.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.22.3"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.4.2"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.0.2"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"59.8.0"
]
]
},
{
"name": "codecarbon",
"specs": [
[
">=",
"2.2.4"
]
]
},
{
"name": "prometheus_client",
"specs": [
[
">=",
"0.17.0"
]
]
}
],
"lcname": "psyki"
}
JSON
