unicode-fol-kit 0.1.0__tar.gz

unicode_fol_kit-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

unicode_fol_kit-0.1.0/.gitignore

@@ -0,0 +1,182 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor  
+#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to 
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+.claude

unicode_fol_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Vossel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unicode_fol_kit-0.1.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: unicode-fol-kit
+Version: 0.1.0
+Summary: Parser and toolkit for first-order logic formulas using Unicode operators
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: lark>=1.1
+Requires-Dist: z3-solver>=4.12
+Description-Content-Type: text/markdown
+
+# unicode-fol-kit
+
+A Python toolkit for parsing and working with first-order logic (FOL) formulas written with Unicode operators.
+
+## Features
+
+- **Parser** — parse FOL formulas using natural Unicode symbols (∀, ∃, ∧, ∨, ¬, →, ↔, ⊕, =, ≠, ≤, ≥)
+- **AST** — full abstract syntax tree with all standard FOL constructs
+- **Serialisation** — convert formulas to/from JSON dictionaries
+- **Tree view** — render any formula as a readable ASCII tree
+- **Z3 export** — translate formulas to Z3 expressions for SMT solving
+- **Prover9 export** — translate formulas to Prover9 syntax for automated theorem proving
+- **TPTP export** — translate formulas to TPTP syntax
+- **Equivalence checking** — check if two formulas are logically equivalent via Z3
+- **Entailment checking** — check if a conclusion follows from premises via Prover9
+
+## Installation
+
+### Via pip
+
+```bash
+pip install unicode-fol-kit
+```
+
+### Via git clone
+
+```bash
+git clone https://github.com/felixvossel/unicode-fol-kit.git
+cd unicode-fol-kit
+pip install .
+```
+
+## Usage
+
+### Parsing a formula
+
+```python
+from unicode_fol_kit import FOLParser
+
+parser = FOLParser()
+formula = parser.parse("∀x (Human(x) → Mortal(x))")
+```
+
+### ASCII tree view
+
+```python
+print(formula.tree_str())
+# ∀ x
+# └── →
+#     ├── Atom: Human
+#     │   └── Variable: x
+#     └── Atom: Mortal
+#         └── Variable: x
+```
+
+### Exporting to other formats
+
+```python
+formula.to_prover9()   # '(all x (Human(x) -> Mortal(x)))'
+formula.to_tptp()      # '(![X]: (human(X) => mortal(X)))'
+formula.to_dict()      # JSON-serialisable dict
+```
+
+### Serialisation
+
+```python
+from unicode_fol_kit import Node
+
+d = formula.to_dict()
+formula2 = Node.from_dict(d)  # round-trip
+```
+
+### Equivalence checking (Z3)
+
+```python
+from unicode_fol_kit import FOLParser, formulas_are_equivalent
+
+parser = FOLParser()
+f1 = parser.parse("¬(P(x) ∧ Q(x))")
+f2 = parser.parse("¬P(x) ∨ ¬Q(x)")
+
+formulas_are_equivalent(f1, f2)  # True
+```
+
+### Entailment checking (Prover9)
+
+```python
+from unicode_fol_kit import FOLParser, check_logical_entailment
+
+parser = FOLParser()
+premises = [
+    parser.parse("∀x (Human(x) → Mortal(x))"),
+    parser.parse("Human(socrates)"),
+]
+conclusion = parser.parse("Mortal(socrates)")
+
+check_logical_entailment(premises, conclusion, prover9_path="/usr/bin/prover9")  # True
+```
+
+## Syntax reference
+
+This section describes the full surface syntax accepted by the parser: which
+symbols are recognised, how terms and formulas are built, and how operator
+precedence and associativity resolve ambiguous input.
+
+### Tokens
+
+The lexer distinguishes the following kinds of identifier, each by a strict
+pattern. Because the categories are separated at the token level, a given
+identifier is unambiguously a variable, a constant, a function/predicate name,
+or a number.
+
+| Token | Pattern | Examples | Meaning |
+|---|---|---|---|
+| Variable | one lowercase letter, optional trailing digits | `x`, `y`, `x1`, `z42` | a (possibly bound) logical variable |
+| Name | lowercase, at least two letters, may contain digits and uppercase after the first letter | `socrates`, `distance`, `centerOf`, `foo1` | a constant or a function symbol |
+| Constant (`c_`) | `c_` followed by letters/digits | `c_a`, `c_zero`, `c_42` | an explicitly marked constant |
+| Predicate | one uppercase letter, then letters/digits | `P`, `Human`, `OnSurfaceOf` | a predicate symbol |
+| Number | digits, optional decimal part | `0`, `42`, `3.14` | a numeric literal |
+
+The `c_` form exists so that **single-letter constants** can be written without
+colliding with variables. A bare `a` is always a variable; if you need the
+constant *a*, write `c_a`.
+
+A function or predicate is recognised by being immediately followed by a
+parenthesised argument list, e.g. `distance(x, y)` or `Human(socrates)`.
+The same identifier class (Name) serves both as a bare constant and, when
+applied, as a function symbol.
+
+### Terms
+
+A term is one of:
+
+- a variable (`x`, `x1`)
+- a constant (`socrates`, `c_a`) or number (`42`, `3.14`)
+- a function application (`f(t1, ..., tn)`, e.g. `centerOf(x)`)
+- an arithmetic combination of terms using `+`, `-`, `*`, `/`
+- a parenthesised term (`(t)`)
+
+Arithmetic follows the usual precedence: `*` and `/` bind tighter than `+` and
+`-`, and both groups are left-associative. For example `x + y * z` parses as
+`x + (y * z)`.
+
+### Atomic formulas
+
+An atomic formula is either:
+
+- a predicate applied to terms: `P`, `Human(socrates)`, `OnSurfaceOf(y, x)`
+  (a predicate may be nullary, i.e. used without arguments)
+- an infix comparison between two terms using `=`, `≠`, `<`, `>`, `≤`, `≥`,
+  e.g. `x1 + 1 = y1` or `distance(y, c) > distance(z, c)`
+
+### Compound formulas
+
+Atomic formulas are combined with the logical connectives and quantifiers:
+
+- negation: `¬φ`
+- conjunction: `φ ∧ ψ`
+- disjunction: `φ ∨ ψ`
+- exclusive or: `φ ⊕ ψ`
+- implication: `φ → ψ`
+- biconditional: `φ ↔ ψ`
+- universal quantification: `∀x φ`
+- existential quantification: `∃x φ`
+
+A formula may be wrapped in parentheses `( … )` or square brackets `[ … ]`;
+the two are interchangeable for grouping.
+
+### Operator precedence
+
+From highest (binds tightest) to lowest (binds loosest):
+
+| Precedence | Operators | Associativity |
+|---|---|---|
+| 1 (highest) | `¬`, quantifiers `∀` / `∃` | prefix |
+| 2 | `∧`, `∨`, `⊕` | left |
+| 3 | `→` | right |
+| 4 (lowest) | `↔` | right |
+
+Worked examples (parenthesised to show how the parser groups them):
+
+- `¬P(x) ∧ Q(x)` → `(¬P(x)) ∧ Q(x)` — negation binds tighter than conjunction
+- `P(x) ∧ Q(x) → R(x)` → `(P(x) ∧ Q(x)) → R(x)` — conjunction binds tighter than implication
+- `P(x) → Q(x) ↔ R(x)` → `(P(x) → Q(x)) ↔ R(x)` — implication binds tighter than biconditional
+- `P(x) → Q(x) → R(x)` → `P(x) → (Q(x) → R(x))` — implication is right-associative
+- `P(x) ∧ Q(x) ∧ R(x)` → `(P(x) ∧ Q(x)) ∧ R(x)` — conjunction is left-associative
+
+### Mixing ∧, ∨ and ⊕
+
+Conjunction, disjunction and exclusive or sit at the **same** precedence level
+and **cannot be mixed without explicit parentheses**. This is deliberate: it
+avoids the silent, easy-to-misread grouping that a default precedence would
+impose. For example:
+
+```text
+P(x) ∧ Q(x) ∨ R(x)        # rejected — ambiguous
+(P(x) ∧ Q(x)) ∨ R(x)      # accepted
+P(x) ∧ (Q(x) ∨ R(x))      # accepted
+```
+
+A chain of the *same* operator is fine: `P ∧ Q ∧ R` and `P ∨ Q ∨ R` both parse.
+
+### Quantifier scope
+
+A quantifier binds **only the immediately following (tightly bound) formula**,
+not the rest of the line. In particular it does *not* automatically extend over
+a following connective. This means:
+
+```text
+∀x P(x) ∧ Q(x)            # parses as (∀x P(x)) ∧ Q(x)
+∀x P(x) → Q(x)            # parses as (∀x P(x)) → Q(x)
+```
+
+If you intend the quantifier to range over the whole implication or
+conjunction — which is usually what is meant — **add parentheses**:
+
+```text
+∀x (P(x) → Q(x))          # quantifier ranges over the implication
+∀x (P(x) ∧ Q(x))          # quantifier ranges over the conjunction
+```
+
+Quantifiers can be stacked directly: `∀x ∀y ∃z φ`.
+
+### Supported symbols
+
+| Category | Symbols |
+|---|---|
+| Quantifiers | `∀` `∃` |
+| Connectives | `∧` `∨` `⊕` `¬` `→` `↔` |
+| Equality / comparison | `=` `≠` `<` `>` `≤` `≥` |
+| Arithmetic | `+` `-` `*` `/` |
+| Grouping | `(` `)` `[` `]` |
+| Argument separator | `,` |
+
+Whitespace is insignificant and may be used freely between tokens.
+
+### A complete example
+
+```text
+∀x ((Object(x) ∧ HasThreeDimensionalShape(x) ∧
+     ∀y ∀z ((Point(y) ∧ OnSurfaceOf(y, x) ∧ Point(z) ∧ OnSurfaceOf(z, x))
+            → distance(y, centerOf(x)) = distance(z, centerOf(x))))
+    → Sphere(x))
+```
+
+This uses unary predicates (`Object`, `Sphere`, `Point`), a binary predicate
+(`OnSurfaceOf`), functions (`distance`, `centerOf`), an infix equality between
+two function terms, nested quantifiers, and explicit parentheses to control
+both the inner implication and the quantifier scope.
+
+## Error handling
+
+Parse errors are reported with human-readable messages rather than raw parser
+internals. Lexer-level problems (an invalid character, a malformed name or
+number) raise `NamingError`; structural problems (an incomplete formula, a
+misplaced operator, or an attempt to mix `∧`/`∨`/`⊕` without parentheses) raise
+`ParsingError`. Both report the offending position and, where useful, a hint.
+
+```python
+from unicode_fol_kit import FOLParser
+
+parser = FOLParser()
+parser.parse("P(x) ∧ Q(x) ∨ R(x)")
+# Parsing/NamingError: SYNTAX_ERROR: Unexpected character '∨' ...
+#   Hint: Cannot mix conjunction (∧), disjunction (∨), and exclusive or (⊕) without parentheses
+```
+
+## Citation
+
+If you use this toolkit in academic work, please cite the accompanying
+preprint:
+
+```bibtex
+@misc{vossel2025advancingnaturallanguageformalization,
+      title={Advancing Natural Language Formalization to First Order Logic with Fine-tuned LLMs},
+      author={Felix Vossel and Till Mossakowski and Björn Gehrke},
+      year={2025},
+      eprint={2509.22338},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL},
+      url={https://arxiv.org/abs/2509.22338},
+}
+```
+
+> Vossel, F., Mossakowski, T., & Gehrke, B. (2025). *Advancing Natural Language
+> Formalization to First Order Logic with Fine-tuned LLMs.* arXiv preprint
+> arXiv:2509.22338.
+
+## License
+
+MIT