| Name | nl2ltl JSON |
| Version |
0.0.6
JSON |
| download |
| home_page | |
| Summary | Natural Language (NL) to Linear Temporal Logic (LTL) |
| upload_time | 2024-02-15 15:41:18 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | <3.11,>=3.8 |
| license | MIT License Copyright (c) 2022 International Business Machines Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
natural language processing
linear temporal logics
generative ai
large language models
process automation
conversational agents
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1>
<b>NL 2 LTL</b>
</h1>
[](https://img.shields.io/pypi/pyversions/nl2ltl)
[](https://img.shields.io/pypi/v/nl2ltl)
[](https://github.com/IBM/nl2ltl/actions/workflows/test.yml/badge.svg)
[](https://github.com/IBM/nl2ltl/actions/workflows/test_gpt.yml/badge.svg)
[](https://github.com/IBM/nl2ltl/actions/workflows/linting.yml/badge.svg)
[](https://github.com/IBM/nl2ltl/actions/workflows/docs.yml/badge.svg)
[](https://codecov.io/github.com/IBM/nl2ltl)
[](https://img.shields.io/github/license/IBM/nl2ltl?color=purple)
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
pip install nl2ltl
```
- from source (`main` branch):
```bash
pip install git+https://github.com/IBM/nl2ltl.git
```
- or clone the repository and install the package:
```bash
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:
```python
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](https://github.com/whitemech/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
- [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
**NOTE**: To use OpenAI GPT models don't forget to add the `OPEN_API_KEY` environment
variable with:
```bash
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:
```python
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:
```python
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:
```python
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:
```python
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](https://developercertificate.org/)
## 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](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},
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "nl2ltl",
"maintainer": "",
"docs_url": null,
"requires_python": "<3.11,>=3.8",
"maintainer_email": "",
"keywords": "natural language processing,linear temporal logics,generative ai,large language models,process automation,conversational agents",
"author": "",
"author_email": "Francesco Fuggitti <francesco.fuggitti@gmail.com>, Tathagata Chakraborti <tchakra2@ibm.com>",
"download_url": "https://files.pythonhosted.org/packages/45/88/47a4c89aac121496c318e5378c44d6da1f900ba6baa811e1caf33bff9ea8/nl2ltl-0.0.6.tar.gz",
"platform": null,
"description": "<h1>\n <b>NL 2 LTL</b>\n</h1>\n\n[](https://img.shields.io/pypi/pyversions/nl2ltl)\n[](https://img.shields.io/pypi/v/nl2ltl)\n[](https://github.com/IBM/nl2ltl/actions/workflows/test.yml/badge.svg)\n[](https://github.com/IBM/nl2ltl/actions/workflows/test_gpt.yml/badge.svg)\n[](https://github.com/IBM/nl2ltl/actions/workflows/linting.yml/badge.svg)\n[](https://github.com/IBM/nl2ltl/actions/workflows/docs.yml/badge.svg)\n[](https://codecov.io/github.com/IBM/nl2ltl)\n[](https://img.shields.io/github/license/IBM/nl2ltl?color=purple)\n\nNL2LTL is an interface to translate natural language (NL) utterances to\nlinear temporal logic (LTL) formulas.\n\n> \ud83c\udfc6 NL2LTL won the People's Choice Best System Demonstration Award Runner-Up in the ICAPS 2023 System Demonstration \n> Track in Prague. Read more about it [here](https://icaps23.icaps-conference.org/demos/papers/6374_paper.pdf).\n\n## Installation\n- from PyPI:\n```bash\npip install nl2ltl\n```\n- from source (`main` branch):\n```bash\npip install git+https://github.com/IBM/nl2ltl.git \n```\n- or clone the repository and install the package:\n```bash\ngit clone https://github.com/IBM/nl2ltl.git\ncd nl2ltl\npip install -e .\n```\n\n## Quickstart\nOnce you have installed all dependencies you are ready to go with:\n```python\nfrom nl2ltl import translate\nfrom nl2ltl.engines.gpt.core import GPTEngine, Models\nfrom nl2ltl.filters.simple_filters import BasicFilter\nfrom nl2ltl.engines.utils import pretty\n\nengine = GPTEngine()\nfilter = BasicFilter()\nutterance = \"Eventually send me a Slack after receiving a Gmail\"\n\nltlf_formulas = translate(utterance, engine, filter)\npretty(ltlf_formulas)\n```\n\nThe `translate` function takes a natural language utterance, an engine and an\noption filter, and outputs the best matching \n[pylogics](https://github.com/whitemech/pylogics) LTL formulas. \n\n\n**NOTE**: Before using the `NL2LTL` translation function, depending on the \nengine you want to use, make sure all preconditions for such an engine are met.\nFor instance, Rasa requires a `.tar.gz` format trained model in the \n`models/` folder to run. To train the model use the available NL2LTL `train(...)` API.\n\n## NLU Engines\n- [x] [GPT-3.x](https://openai.com/api/) large language models\n- [x] [GPT-4](https://openai.com/api/) large language model\n- [x] [Rasa](https://rasa.com/) intents/entities classifier (to use Rasa, please install it with `pip install -e \".[rasa]\"`)\n- [ ] [Watson Assistant](https://www.ibm.com/products/watson-assistant) intents/entities classifier -- Planned\n\n**NOTE**: To use OpenAI GPT models don't forget to add the `OPEN_API_KEY` environment\nvariable with:\n```bash\nexport OPENAI_API_KEY=your_api_key\n```\n\n## Write your own Engine\nYou can easily write your own engine (i.e., intents/entities classifier, \nlanguage model, etc.) by implementing the Engine interface:\n\n```python\nfrom nl2ltl.engines.base import Engine\nfrom pylogics.syntax.base import Formula\n\nclass MyEngine(Engine):\n\n def translate(self, utterance: str, filtering: Filter) -> Dict[Formula, float]:\n \"\"\"From NL to LTL.\"\"\"\n```\n\nThen, use it as a parameter in the main entry point:\n```python\nmy_engine = MyEngine()\nltl_formulas = translate(utterance, engine=my_engine)\n```\n\n## Write your own Filter\nYou can easily write your own filtering algorithm by implementing \nthe Filter interface:\n\n```python\nfrom nl2ltl.filters.base import Filter\nfrom pylogics.syntax.base import Formula\n\nclass MyFilter(Filter):\n\n def enforce(\n self, output: Dict[Formula, float], entities: Dict[str, float], **kwargs\n ) -> Dict[Formula, float]:\n \"\"\"Filtering algorithm.\"\"\"\n```\n\nThen, use it as a parameter in the main entry point:\n```python\nmy_engine = MyEngine()\nmy_filter = MyFilter()\nltl_formulas = translate(utterance, engine=my_engine, filter=my_filter)\n```\n\n## Development\n\nContributions are welcome! Here's how to set up the development environment:\n- set up your preferred virtualenv environment\n- clone the repo: `git clone https://github.com/IBM/nl2ltl.git && cd nl2ltl`\n- install dependencies: `pip install -e .`\n- install dev dependencies: `pip install -e \".[dev]\"`\n- install pre-commit: `pre-commit install`\n- sign-off your commits using the `-s` flag in the commit message to be compliant with \nthe [DCO](https://developercertificate.org/)\n\n## Tests\n\nTo run tests: `tox`\n\nTo run the code tests only: `tox -e py310`\n\n## Docs\n\nTo build the docs: `mkdocs build`\n\nTo view documentation in a browser: `mkdocs serve`\nand then go to [http://localhost:8000](http://localhost:8000)\n\n## Citing\n\n```\n@inproceedings{icaps2023fc,\n author = {Francesco Fuggitti and Tathagata Chakraborti},\n title = {{NL2LTL} -- A Python Package for Converting Natural Language ({NL}) Instructions to Linear Temporal Logic ({LTL}) Formulas},\n booktitle = {{ICAPS}},\n year = {2023},\n note = {Best System Demonstration Award Runner-Up.},\n url_code = {https://github.com/IBM/nl2ltl},\n}\n```\nand\n```\n@inproceedings{aaai2023fc,\n author = {Francesco Fuggitti and Tathagata Chakraborti},\n title = {{NL2LTL} -- A Python Package for Converting Natural Language ({NL}) Instructions to Linear Temporal Logic ({LTL}) Formulas},\n booktitle = {{AAAI}},\n year = {2023},\n note = {System Demonstration.},\n url_code = {https://github.com/IBM/nl2ltl},\n}\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022 International Business Machines Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Natural Language (NL) to Linear Temporal Logic (LTL)",
"version": "0.0.6",
"project_urls": {
"Issues": "https://github.com/IBM/nl2ltl/issues",
"Repository": "https://github.com/IBM/nl2ltl"
},
"split_keywords": [
"natural language processing",
"linear temporal logics",
"generative ai",
"large language models",
"process automation",
"conversational agents"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "564ac38b789548e896566c01a1c48f8a149374f3b4ccabe63b8ac58d3c34850e",
"md5": "65705fa1f9f03c811cc34e6f9ae9fa00",
"sha256": "6b2dc063fa39661a741b57db771984361ed56ac49137750483d2bb832d5e4bc9"
},
"downloads": -1,
"filename": "nl2ltl-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65705fa1f9f03c811cc34e6f9ae9fa00",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.11,>=3.8",
"size": 21793,
"upload_time": "2024-02-15T15:41:14",
"upload_time_iso_8601": "2024-02-15T15:41:14.864084Z",
"url": "https://files.pythonhosted.org/packages/56/4a/c38b789548e896566c01a1c48f8a149374f3b4ccabe63b8ac58d3c34850e/nl2ltl-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "458847a4c89aac121496c318e5378c44d6da1f900ba6baa811e1caf33bff9ea8",
"md5": "0e116cbd2d12a7978f0636f6398e4a9a",
"sha256": "af7a1ec45d858aa4901389b89cb7d53c93ce10374eb7855a2b7c05974f301cce"
},
"downloads": -1,
"filename": "nl2ltl-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "0e116cbd2d12a7978f0636f6398e4a9a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.11,>=3.8",
"size": 18278,
"upload_time": "2024-02-15T15:41:18",
"upload_time_iso_8601": "2024-02-15T15:41:18.485877Z",
"url": "https://files.pythonhosted.org/packages/45/88/47a4c89aac121496c318e5378c44d6da1f900ba6baa811e1caf33bff9ea8/nl2ltl-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-15 15:41:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IBM",
"github_project": "nl2ltl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "nl2ltl"
}
