Natural Language (NL) to Linear Temporal Logic (LTL)
Project description
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},
}
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
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | af7a1ec45d858aa4901389b89cb7d53c93ce10374eb7855a2b7c05974f301cce |
|
MD5 | 0e116cbd2d12a7978f0636f6398e4a9a |
|
BLAKE2b-256 | 458847a4c89aac121496c318e5378c44d6da1f900ba6baa811e1caf33bff9ea8 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6b2dc063fa39661a741b57db771984361ed56ac49137750483d2bb832d5e4bc9 |
|
MD5 | 65705fa1f9f03c811cc34e6f9ae9fa00 |
|
BLAKE2b-256 | 564ac38b789548e896566c01a1c48f8a149374f3b4ccabe63b8ac58d3c34850e |