Skip to main content

Natural Language (NL) to Linear Temporal Logic (LTL)

Project description

NL 2 LTL

Python PyPI Test TestGPT Lint Docs codecov LICENSE

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},
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nl2ltl-0.0.6.tar.gz (18.3 kB view hashes)

Uploaded Source

Built Distribution

nl2ltl-0.0.6-py3-none-any.whl (21.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page