NL 2 LTL

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.

Installation

• from PyPI:

pip install nl2ltl

• from source (main branch):

pip install git+https://github.com/IBM/nl2ltl.git 

• or clone the repository and install the package:

git clone https://github.com/IBM/nl2ltl.git
cd nl2ltl
pip install -e .

Quickstart

Once you have installed all dependencies you are ready to go with:

from nl2ltl import translate
from nl2ltl.engines.gpt.core import GPTEngine, Models
from nl2ltl.filters.simple_filters import BasicFilter
from nl2ltl.engines.utils import pretty

engine = GPTEngine()
filter = BasicFilter()
utterance = "Eventually send me a Slack after receiving a Gmail"

ltlf_formulas = translate(utterance, engine, filter)
pretty(ltlf_formulas)

The translate function takes a natural language utterance, an engine and an option filter, and outputs the best matching pylogics LTL formulas.

NOTE: Before using the NL2LTL translation function, depending on the engine you want to use, make sure all preconditions for such an engine are met. 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

• GPT-3.x large language models
• GPT-4 large language model
• Rasa intents/entities classifier (to use Rasa, please install it with pip install -e ".[rasa]")
• Watson Assistant intents/entities classifier -- Planned

NOTE: To use OpenAI GPT models don't forget to add the OPEN_API_KEY environment variable with:

export OPENAI_API_KEY=your_api_key

Write your own Engine

You can easily write your own engine (i.e., intents/entities classifier, language model, etc.) by implementing the Engine interface:

from nl2ltl.engines.base import Engine
from pylogics.syntax.base import Formula

class MyEngine(Engine):

    def translate(self, utterance: str, filtering: Filter) -> Dict[Formula, float]:
        """From NL to LTL."""

Then, use it as a parameter in the main entry point:

my_engine = MyEngine()
ltl_formulas = translate(utterance, engine=my_engine)

Write your own Filter

You can easily write your own filtering algorithm by implementing the Filter interface:

from nl2ltl.filters.base import Filter
from pylogics.syntax.base import Formula

class MyFilter(Filter):

    def enforce(
        self, output: Dict[Formula, float], entities: Dict[str, float], **kwargs
    ) -> Dict[Formula, float]:
    """Filtering algorithm."""

Then, use it as a parameter in the main entry point:

my_engine = MyEngine()
my_filter = MyFilter()
ltl_formulas = translate(utterance, engine=my_engine, filter=my_filter)

Development

Contributions are welcome! Here's how to set up the development environment:

• set up your preferred virtualenv environment
• clone the repo: git clone https://github.com/IBM/nl2ltl.git && cd nl2ltl
• install dependencies: pip install -e .
• install dev dependencies: pip install -e ".[dev]"
• install pre-commit: pre-commit install
• sign-off your commits using the -s flag in the commit message to be compliant with the DCO

Tests

To run tests: tox

To run the code tests only: tox -e py310

Docs

To build the docs: mkdocs build

To view documentation in a browser: mkdocs serve and then go to http://localhost:8000

Citing

@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    = {{ICAPS}},
  year         = {2023},
  note         = {Best System Demonstration Award Runner-Up.},
  url_code     = {https://github.com/IBM/nl2ltl},
}

and

@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    = {{AAAI}},
  year         = {2023},
  note         = {System Demonstration.},
  url_code     = {https://github.com/IBM/nl2ltl},
}