Merge pull request #28 from IBM/dev

Release candidate 0.0.5

.github/workflows/docs.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8"]
+        python-version: ["3.10"]
 
     timeout-minutes: 30
 

.github/workflows/linting.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8"]
+        python-version: ["3.10"]
 
     timeout-minutes: 30
 
@@ -25,4 +25,5 @@ jobs:
     - name: Install dependencies
       run:  pip install tox
     - name: Code style check
-      run:  tox -e precommit
+      run: |
+        tox -e ruff-format,ruff-check

.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8"]
+        python-version: ["3.10"]
 
     timeout-minutes: 30
 
@@ -25,8 +25,9 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest pytest-cov pytest-randomly hypothesis-pytest
-        pip install -r requirements.txt
+        pip install pytest && pip install pytest-cov
+        pip install -e .
+        pip install -e ".[rasa]"
     - name: Unit tests and coverage
       run: |
         pytest -k "not gpt" \
@@ -36,7 +37,6 @@ jobs:
         --cov-report=xml \
         --cov-report=html \
         --cov-report=term \
-        --hypothesis-show-statistics
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3
       with:

.github/workflows/test_gpt.yml

@@ -9,7 +9,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8"]
+        python-version: ["3.10"]
 
     timeout-minutes: 30
 
@@ -21,8 +21,8 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest pytest-cov pytest-randomly hypothesis-pytest
-        pip install -r requirements.txt
+        pip install pytest
+        pip install -e .
     - name: Unit tests and coverage
       run: |
         pytest test_gpt.py \
@@ -32,7 +32,6 @@ jobs:
         --cov-report=xml \
         --cov-report=html \
         --cov-report=term \
-        --hypothesis-show-statistics
       env:
         OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
     - name: Upload coverage to Codecov

CHANGES.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## 0.0.5 (2024-02-10)
+
+* Make Rasa an optional package.
+* Update OpenAI GPT models.
+* Update Python version.
+* Update building tools.
+
 ## 0.0.4 (2023-07-07)
 
 * Fix the grounding process of formulas.

README.md

@@ -14,6 +14,9 @@
 NL2LTL is an interface to translate natural language (NL) utterances to
 linear temporal logic (LTL) formulas.
 
+> 🏆 NL2LTL won the People's Choice Best System Demonstration Award Runner-Up in the ICAPS 2023 System Demonstration 
+> Track in Prague. Read more about it [here](https://icaps23.icaps-conference.org/demos/papers/6374_paper.pdf).
+
 ## Installation
 - from PyPI:
 ```bash
@@ -27,7 +30,7 @@ pip install git+https://github.com/IBM/nl2ltl.git
 ```bash
 git clone https://github.com/IBM/nl2ltl.git
 cd nl2ltl
-pip install .
+pip install -e .
 ```
 
 ## Quickstart
@@ -57,12 +60,12 @@ For instance, Rasa requires a `.tar.gz` format trained model in the
 `models/` folder to run. To train the model use the available NL2LTL `train(...)` API.
 
 ## NLU Engines
-- [x] [Rasa](https://rasa.com/) intents/entities classifier
 - [x] [GPT-3.x](https://openai.com/api/) large language models
 - [x] [GPT-4](https://openai.com/api/) large language model
+- [x] [Rasa](https://rasa.com/) intents/entities classifier (to use Rasa, please install it with `pip install -e ".[rasa]"`)
 - [ ] [Watson Assistant](https://www.ibm.com/products/watson-assistant) intents/entities classifier -- Planned
 
-To use GPT models you need to have an API KEY set as environment variable. To set it:
+To use GPT models you need to have the OPEN_API_KEY set as environment variable. To set it:
 ```bash
 export OPENAI_API_KEY=your_api_key
 ```
@@ -113,17 +116,15 @@ ltl_formulas = translate(utterance, engine=my_engine, filter=my_filter)
 ## Development
 
 Contributions are welcome! Here's how to set up the development environment:
-- install [Pipenv](https://pipenv-fork.readthedocs.io/en/latest/)
+- set up your preferred virtualenv environment
 - clone the repo: `git clone https://github.com/IBM/nl2ltl.git && cd nl2ltl`
-- install dev dependencies: `pipenv shell --python 3.8 && pipenv install --dev`
+- install dev dependencies: `pip install -e ".[dev]"`
 
 ## Tests
 
 To run tests: `tox`
 
-To run the code tests only: `tox -e py3.8`
-
-To run the code style checks only: `tox -e precommit`
+To run the code tests only: `tox -e py310`
 
 ## Docs
 
@@ -135,24 +136,23 @@ and then go to [http://localhost:8000](http://localhost:8000)
 ## Citing
 
 ```
-@inproceedings{aaai2023fc,
+@inproceedings{icaps2023fc,
   author       = {Francesco Fuggitti and  Tathagata Chakraborti},
   title        = {{NL2LTL} -- A Python Package for Converting Natural Language ({NL}) Instructions to Linear Temporal Logic ({LTL}) Formulas},
-  booktitle    = {{AAAI}},
+  booktitle    = {{ICAPS}},
   year         = {2023},
-  note         = {System Demonstration.},
+  note         = {Best System Demonstration Award Runner-Up.},
   url_code     = {https://github.com/IBM/nl2ltl},
 }
 ```
 and
 ```
-@inproceedings{icaps2023fc,
+@inproceedings{aaai2023fc,
   author       = {Francesco Fuggitti and  Tathagata Chakraborti},
   title        = {{NL2LTL} -- A Python Package for Converting Natural Language ({NL}) Instructions to Linear Temporal Logic ({LTL}) Formulas},
-  booktitle    = {{ICAPS}},
+  booktitle    = {{AAAI}},
   year         = {2023},
   note         = {System Demonstration.},
   url_code     = {https://github.com/IBM/nl2ltl},
 }
 ```
-

mkdocs.yml

@@ -1,6 +1,6 @@
 site_name: NL2LTL
 repo_name: 'NL2LTL'
-repo_url: https://github.ibm.com/Francesco-Fuggitti/nl2ltl
+repo_url: https://github.com/IBM/nl2ltl
 
 nav:
 - Home: index.md

nl2ltl/__init__.py

@@ -1,7 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """From Natural Language to Linear-time Temporal Logic on Finite Traces."""
 
-__version__ = "0.0.4"
-
 from .core import translate  # noqa: F401

nl2ltl/core.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """NL2LTLf core module."""
 from typing import Dict
 
@@ -17,11 +15,8 @@ def _call_translation_method(
     return method(utterance, filtering)
 
 
-def translate(
-    utterance: str, engine: Engine, filtering: Filter = None
-) -> Dict[Formula, float]:
-    """
-    From NL to LTLf.
+def translate(utterance: str, engine: Engine, filtering: Filter = None) -> Dict[Formula, float]:
+    """From NL to LTLf.
 
     :param utterance: the natural language utterance to translate.
     :param engine: the engine to use.

nl2ltl/declare/__init__.py

@@ -1,3 +1 @@
-# -*- coding: utf-8 -*-
-
 """Implementation of DECLARE templates."""

nl2ltl/declare/base.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Base classes for declare templates."""
 
 from abc import abstractmethod

nl2ltl/declare/declare.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Classes for declare templates."""
 from pylogics.syntax.base import And, Formula, Implies, Not, Or, _BinaryOp, _UnaryOp
 from pylogics.syntax.ltl import Always, Eventually, Next, Until
@@ -120,16 +118,11 @@ def to_ltlf(self) -> Formula:
 
     def to_english(self) -> str:
         """English meaning."""
-        return (
-            f"Whenever  {self.operands[0]} happens,  {self.operands[1]} has to happen "
-            f"eventually afterward."
-        )
+        return f"Whenever  {self.operands[0]} happens,  {self.operands[1]} has to happen " f"eventually afterward."
 
     def to_ppltl(self) -> Formula:
         """Translate Response to PPLTL."""
-        return Not(
-            Since(Not(self.operands[1]), And(self.operands[0], Not(self.operands[1])))
-        )
+        return Not(Since(Not(self.operands[1]), And(self.operands[0], Not(self.operands[1]))))
 
 
 class Precedence(Template, _BinaryOp):
@@ -151,10 +144,7 @@ def to_ltlf(self) -> Formula:
 
     def to_english(self) -> str:
         """English meaning."""
-        return (
-            f"Whenever  {self.operands[1]} happens,  {self.operands[0]} has to have happened "
-            f"before it."
-        )
+        return f"Whenever  {self.operands[1]} happens,  {self.operands[0]} has to have happened " f"before it."
 
     def to_ppltl(self) -> Formula:
         """Translate Precedence to PPLTL."""

nl2ltl/declare/misc.py

@@ -1,15 +1,11 @@
-# -*- coding: utf-8 -*-
-
 """Helper functions."""
 from typing import Sequence, Type
 
 from pylogics.syntax.base import Formula
 from pylogics.syntax.ltl import Atomic
 
 
-def _enforce(
-    condition: bool, message: str = "", exception_cls: Type[Exception] = AssertionError
-):
+def _enforce(condition: bool, message: str = "", exception_cls: Type[Exception] = AssertionError):
     """User-defined assert."""
     if not condition:
         raise exception_cls(message)

nl2ltl/engines/__init__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Engines for nl2ltl."""
 
 from nl2ltl.engines.base import Engine  # noqa: F401

nl2ltl/engines/base.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Abstract definition of a engine."""
 from abc import ABC, ABCMeta
 from typing import Dict
@@ -13,8 +11,6 @@
 class _MetaEngine(ABCMeta):
     """Metaclass for rasa."""
 
-    # TODO: Do some Engine validation here? e.g., we may want to check whether certain parameters are present
-
     def __new__(mcs, *args, **kwargs):
         """Instantiate a new class."""
         return super().__new__(mcs, *args, **kwargs)
@@ -26,15 +22,10 @@ class Engine(ABC, metaclass=_MetaEngine):
     @classmethod
     def __not_supported_error(cls, operation: str) -> Exception:
         """Raise a not supported error."""
-        return NotImplementedEngineFunction(
-            f"operation '{operation}' is not supported by the '{cls.__name__}' engine"
-        )
+        return NotImplementedEngineFunction(f"operation '{operation}' is not supported by the '{cls.__name__}' engine")
 
-    def translate(
-        self, utterance: str, filtering: Filter = None
-    ) -> Dict[Formula, float]:
-        """
-        Transform a Natural Language utterance into an LTLf formula.
+    def translate(self, utterance: str, filtering: Filter = None) -> Dict[Formula, float]:
+        """Transform a Natural Language utterance into an LTLf formula.
 
         :param utterance: a Natural Language utterance
         :param filtering: a custom filtering algorithm

nl2ltl/engines/gpt/__init__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Implementation of the GPT engine."""
 
 import inspect