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 details)

Uploaded Source

Built Distribution

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

Uploaded Python 3

File details

Details for the file nl2ltl-0.0.6.tar.gz.

File metadata

  • Download URL: nl2ltl-0.0.6.tar.gz
  • Upload date:
  • Size: 18.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.9.18

File hashes

Hashes for nl2ltl-0.0.6.tar.gz
Algorithm Hash digest
SHA256 af7a1ec45d858aa4901389b89cb7d53c93ce10374eb7855a2b7c05974f301cce
MD5 0e116cbd2d12a7978f0636f6398e4a9a
BLAKE2b-256 458847a4c89aac121496c318e5378c44d6da1f900ba6baa811e1caf33bff9ea8

See more details on using hashes here.

File details

Details for the file nl2ltl-0.0.6-py3-none-any.whl.

File metadata

  • Download URL: nl2ltl-0.0.6-py3-none-any.whl
  • Upload date:
  • Size: 21.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.9.18

File hashes

Hashes for nl2ltl-0.0.6-py3-none-any.whl
Algorithm Hash digest
SHA256 6b2dc063fa39661a741b57db771984361ed56ac49137750483d2bb832d5e4bc9
MD5 65705fa1f9f03c811cc34e6f9ae9fa00
BLAKE2b-256 564ac38b789548e896566c01a1c48f8a149374f3b4ccabe63b8ac58d3c34850e

See more details on using hashes here.

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