Metadata-Version: 2.4
Name: clgc
Version: 2.2.0
Summary: A Python package to translate First-Order Logic (FOL) into different knowledge representation languages
Author-email: Hanna Abi Akl <hannaabiakl8@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/HannaAbiAkl/clgc
Project-URL: Issues, https://github.com/HannaAbiAkl/clgc/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

![alt text for screen readers](https://raw.githubusercontent.com/hannaabiakl/clgc/main/logo.png "CLGC")

# CLGC

A Python package to translate First-Order Logic (FOL) into different knowledge representation languages.

## Scope

A package used for handling logic statements and logic analysis using formal knowledge representation languages.

Related literature cover architecture [[1]](#ref-1) and experiments [[2]](#ref-2),[[4]](#ref-4).

## Architecture

![alt text for screen readers](https://raw.githubusercontent.com/hannaabiakl/clgc/main/figures/fig1.png "Architecture")

Formal languages (notations) are treated as objects starting with a base abstract class *Notation*. Any formal language is defined from the *Notation* class using its Backus–Naur form [(BNF)](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form) grammar.

The package also supports the creation of user-defined (custom) notations as long as they have a defined BNF grammar.

The easiest entry point for a new notation is by extending FOL (the default notation for manipulating syllogisms in the package).

## Key Features

![alt text for screen readers](https://raw.githubusercontent.com/hannaabiakl/clgc/main/figures/fig2.png "Features")

- Manipulate syllogisms as objects
- Translate FOL statements to other formal Knowledge Representation (KR) languages
- Categorize syllogisms by type
- Validate KR notations

## Supported KR Languages

- Common Logic Interchange Format (CLIF)
- Conceptual Graph Interchange Format (CGIF)
- Tensor Function Logic (TFL)
- Tensor Function Logic Plus (TFL+)
- CLINGO
- MINIFOL*x*
- PROLOG

## Setup

Start by installing the package

`pip install clgc`

Then install the dependencies

`pip install -r requirements.txt`

## Basic Usage

To load all functionalities

`from clgc.__base import *`

To create a valid syllogism in FOL, each statement of the syllogism should be followed by the `'\n'` terminator. The following example creates a syllogism of 2 premises and a conclusion:

```python
syllogism = FOLSyllogism("∀x (Bikes(x) → ¬Calledcars(x))\n ∀x (Bike(x) → Vehicle(x))\n ∃x (Vehicles(x) ∧ Bikes(x))\n")
```

To categorize syllogisms in natural language or first-order language

```python
syllogism = FOLSyllogism("∀x (Bikes(x) → ¬Calledcars(x))\n ∀x (Bike(x) → Vehicle(x))\n ∃x (Vehicles(x) ∧ Bikes(x))\n")

print
(syllogism.categorize())
# categorical
```

To translate from first-order language to another language (here, TFL+)

```python
# get syllogism as text
test_syllogism = FOLSyllogism("∀x (Bikes(x) → ¬Calledcars(x))\n ∀x (Bike(x) → Vehicle(x))\n ∃x (Vehicles(x) ∧ Bikes(x))\n").syllogism
# convert to desired logical notation - here TFL+
tfl_plus_syllogism = FOLSyllogism.fol_to_tfl_plus(test_syllogism)

print(tfl_syllogism)
# -(+B0--+C0)-(+B0-+V0)+(+V1++B1)
```

A list of functions are available to modify a syllogism:
- `add_statements` (automatically adds the given statements in that order meaning the last given statement becomes the conclusion of the syllogism)
- `add_premises` (automatically keeps the original conclusion and adds everything given as premises)
- `add_conclusion` (automatically takes the given statement as the conclusion and renders everything else to premises)

An example of adding new statements

```python
test_syllogism = FOLSyllogism("∃x (Canine(x) ∧ ¬AquaticCreatureKnownAsFish(x))\n")
        test_syllogism.add_statements(["∀x (Fish(x) → ¬MammalThereforeEveryCanineFallUnderTheCategoryOfMammal(x))\n"])   

print(test_syllogism.statements)
# ["∃x (Canine(x) ∧ ¬AquaticCreatureKnownAsFish(x))", "∀x (Fish(x) → ¬MammalThereforeEveryCanineFallUnderTheCategoryOfMammal(x))"])
```

An example of adding new premises

```python
test_syllogism = FOLSyllogism("∃x (Canine(x) ∧ ¬AquaticCreatureKnownAsFish(x))\n ∀x (Bike(x) → Vehicle(x))\n")
        test_syllogism.add_premises(["∀x (Fish(x) → ¬MammalThereforeEveryCanineFallUnderTheCategoryOfMammal(x))\n"]) 

print(test_syllogism.premises)
# ["∃x (Canine(x) ∧ ¬AquaticCreatureKnownAsFish(x))", "∀x (Fish(x) → ¬MammalThereforeEveryCanineFallUnderTheCategoryOfMammal(x))"]
```

An example of adding a new conclusion

```python
test_syllogism = FOLSyllogism("∃x (Canine(x) ∧ ¬AquaticCreatureKnownAsFish(x))\n ∀x (Bike(x) → Vehicle(x))\n")
        test_syllogism.add_conclusion("∀x (Fish(x) → ¬MammalThereforeEveryCanineFallUnderTheCategoryOfMammal(x))\n") 

print(test_syllogism.conclusion)
# "∀x (Fish(x) → ¬MammalThereforeEveryCanineFallUnderTheCategoryOfMammal(x))"
```

## Integration
As CLGC manipulates logical notations, it can be integrated with other logic programming libraries.
### Pytholog
The example below is adapted from Pytholog [[3]](#ref-3) to show how CLGC objects can be leveraged to write and validate correct logical programming notations like PROLOG.

**<ins>_Note:</ins> You should make sure to install the dependencies of the target library integrations._**

```python
import pytholog as pl
from clgc.__base import *

clgc_kb = pl.KnowledgeBase("clgc_flavor")
clgc_list = ["likes(noor, sausage)",
        "likes(melissa, pasta)",
        "likes(dmitry, cookie)",
        "likes(nikita, sausage)",
        "likes(assel, limonade)",
        "food_type(gouda, cheese)",
        "food_type(ritz, cracker)",
        "food_type(steak, meat)",
        "food_type(sausage, meat)",
        "food_type(limonade, juice)",
        "food_type(cookie, dessert)",
        "flavor(sweet, dessert)",
        "flavor(savory, meat)",
        "flavor(savory, cheese)",
        "flavor(sweet, juice)",
        "food_flavor(X, Y) :- food_type(X, Z), flavor(Y, Z)",
        "dish_to_like(X, Y) :- likes(X, L), food_type(L, T), flavor(F, T), food_flavor(Y, F), neq(L, Y)"]
# validate if every fact in the list is in prolog
# if so, add it to the db
# if not, interrupt the program
for statement in clgc_list:
    prolog_syllogism = FOLSyllogism(statement + " .\n")
    try:
        prolog_syllogism.validate(grammar='PROLOG')
    except Exception as e:
        raise Exception(f"Failed to parse Prolog string: {e}")

# now everything that is added is valid
clgc_kb(clgc_list)

# query the db in clgc
query_str = "likes(noor, sausage)"
query = FOLSyllogism(statement + " .\n")
# check if query is valid
# if yes, query the db for an answer
# if not, interrupt the program
try:
    query.validate(grammar='PROLOG')
    print(clgc_kb.query(pl.Expr(query_str)))
except Exception as e:
    raise Exception(f"Failed to parse Prolog string: {e}")
# ['Yes']
```

## Syllogisms as Graphs
![alt text for screen readers](https://raw.githubusercontent.com/hannaabiakl/clgc/main/figures/fig3.png "CLGC-Graphs")

CLGC is evolving! Syllogisms can now be represented as graphs to explore topological features and detect syllogistic fallacies.

Here is an example usage and the generated graph in FOL:
```python
test_syllogism = FOLSyllogism("∀x (Tiger(x) → Cat(x))\n∀x (Cat(x) → ¬Dog(x))\n∀x (BengalTiger(x) → Tiger(x))\n∀x (Husky(x) → Dog(x))\nBengalTiger(fido) ⊕ Cat(fido)\n")
test_syllogism.add_conclusion("Husky(fido)")
# transform flat syllogism to graph
fol_syllogism_graph = FOLSyllogism.ast_to_syllogism_graph(test_syllogism.syllogism+'\n')
print("Syllogism Graph:")
print(fol_syllogism_graph)
# plot the graph
FOLSyllogism.plot_syllogism_pyvis(fol_syllogism_graph, output_filename="fol_syllogism_graph.html")
```

And the ensuing graph representation

![alt text for screen readers](https://raw.githubusercontent.com/hannaabiakl/clgc/main/figures/fig4.png "FOL-Graph")


## References
1. <span id=ref-1>Hanna Abi Akl. Investigating Language Model Capabilities to Represent and Process Formal Knowledge: A Preliminary Study to Assist Ontology Engineering. The International Joint Conference on Rules and Reasoning (RuleML+RR) 2025, Sep 2025, Instabul, Turkey. ⟨hal-05248053v2⟩. [[paper]](https://inria.hal.science/hal-05248053)</span>
2. <span id=ref-2>Hanna Abi Akl, Fabien Gandon, Catherine Faron, Pierre Monnin. SEF-CLGC at SemEval-2026 Task 11: Logical Notation Impact on Language Model Performance. SemEval-2026 - The 20th International Workshop on Semantic Evaluation, Jul 2026, San Diego (California), United States. ⟨hal-05606250⟩. [[paper]](https://hal.science/hal-05606250)</span></span>
3. <span id=ref-3>MNoorFawi. (n.d.). GitHub - MNoorFawi/pytholog: Python library that enables using prolog syntax and logic programming in python. GitHub. [[code]](https://github.com/MNoorFawi/pytholog/tree/master?tab=readme-ov-file)</span>
4. <span id=ref-4>Hanna Abi Akl, Fabien Gandon, Catherine Faron, Pierre Monnin. Are you Talking Logic to Me? Assessing Language Models Syllogistic Reasoning Capabilities. The International Joint Conference on Rules and Reasoning (RuleML+RR) 2026, Aug 2026, Vilnius, Lithuania. ⟨hal-05700643⟩. [[paper]](https://hal.science/hal-05700643)</span></span>
