psyki 0.2.1.dev1

Python-based implementation of PSyKI, i.e. a Platform for Symbolic Knowledge Injection

PSyKI

Some quick links:

• GitHub Repository
• PyPi Repository
• 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:

@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 library for Symbolic Knowledge Injection (SKI) into sub-symbolic predictors. PSyKI offers SKI algorithms (injectors), and it is open to extendability.

An Injector is a SKI algorithm that takes a sub-symbolic predictor and prior symbolic knowledge, and it creates a new predictor through method inject. Knowledge can be represented in many ways, the most common is the representation via textual logic formulae. Currently, (stratified) Datalog formulae (allowing negation) are supported. Knowledge in this form should be processed into a visitable data structure Formula that is specific w.r.t. the representation. User can use the Antlr adapter to get proper Formula from the AST generated by antlr4. Knowledge represented via Formula object can be embedded in a sub-symbolic form through a Fuzzifier. A Fuzzifier is a visitor for Formula objects that outputs a sub-symbolic object that can be injected into a sub-symbolic predictor.

Currently, implemented injectors are:

• LambdaLayer, performs injection into NN of any shape via constraining;
• NetworkComposer, performs injection into NN of any shape via structuring.

Users

PSyKI is deployed as a library on Pypi, and it can therefore be installed as Python pachage by running:

pip install psyki

Requirements

• python 3.9+
• java 11 (for test and demo)
• antlr4-python3-runtime 4.9.3 (for test and demo)
• tensorflow 2.6.2
• numpy 1.19.2
• scikit-learn 1.0.1
• pandas 1.3.4

Demo

demo/demo.ipynb is a notebook that shows how injection is applied to a network for poker hand classification task. Rules are defined in resources/rules/poker.csv.

Example of injection:

injector = NetworkComposer(model, feature_mapping)
predictor = injector.inject(formulae)
predictor.compile(optimizer=Adam(), loss='sparse_categorical_crossentropy', metrics=['accuracy'])
predictor.fit(train_x, train_y, verbose=1, batch_size=32, epochs=100)

Output:

Epoch 1/100
782/782 [==============================] - 3s 906us/step - loss: 1.0029 - accuracy: 0.5090
Epoch 2/100
782/782 [==============================] - 1s 902us/step - loss: 0.9579 - accuracy: 0.5381
Epoch 3/100
782/782 [==============================] - 1s 899us/step - loss: 0.9447 - accuracy: 0.5451
Epoch 4/100
782/782 [==============================] - 1s 903us/step - loss: 0.9347 - accuracy: 0.5534
Epoch 5/100
782/782 [==============================] - 1s 896us/step - loss: 0.9249 - accuracy: 0.5547
Epoch 6/100
782/782 [==============================] - 1s 897us/step - loss: 0.9153 - accuracy: 0.5625

loss, accuracy = predictor.evaluate(test_x, test_y)
print('Loss: ' + str(loss))
print('Accuracy: ' + str(accuracy))

Output:

31250/31250 [==============================] - 26s 822us/step - loss: 0.0660 - accuracy: 0.9862
Loss: 0.06597686558961868
Accuracy: 0.9862030148506165

Developers

Working with PSyKE 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 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, 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 PSyKE, you are encouraged to signal it through the project "Issues" section on GitHub.