Lemming

This repository hosts the source code for Lemming: A Guided Disambiguation Tool for Plan Selection. Lemming makes use of landmarks to proactively guide the user to select a plan from a set of plans while greedily minimizing the number of disambiguation points. It also provides multiple views into the set of plans that need to be disambiguated, reflecting different considerations for the user in terms of how much information they need to deal with during the disambiguation process.

🏆 The first Lemming appears in the ICAPS 2023 System Demonstration Track in Prague, where its integration with the NL2LTL package was the runners-up for the People's Choice Best System Demonstration Award. Read more about it here.

Run Docker Images

Pull down the repository.

user:~$ git clone git@github.com:IBM/lemming.git --recursive
user:~$ cd lemming

Build a front-end image.

user:~$ yarn install
user:~$ yarn build

To build a Backend image, pip can be configured with pip.conf at the project root. This is to go around sporadic python index server issues. Your OpenAI API Key (OPENAI_API_KEY) should be defined in backend.env to use NL2LTL service at the backend. For security, backend.env should be removed after the deployment.

To bring up Lemming service,

docker-compose --env-file backend.env -f docker-compose.yml up

To teardown Lemming service,

docker-compose -f docker-compose.yml down

Setting up locally

Clone the repository and its submodules

user:~$ git clone git@github.com:IBM/lemming.git --recursive
user:~$ cd lemming

Change to a virtual environment

We also strongly recommend using a virtual environment, such as anaconda, for development.

user:~$ conda create --name lemming python=3.10.11
user:~$ conda activate lemming

Install Lemming Dependencies

(lemming) user:~$ pip install -e .

Use the NL2LTL integration (optional)

First, install nl2ltl and plan4past with:

(lemming) user:~$ pip install -e ".[nl2ltl]"

Then, build the symk planner with:

(lemming) user:~$ ./scripts/build-submodules.sh

(Make sure you have autoconf, automake, cmake, g++, libtool, and make pre-installed on your system).

In order to use the NL2LTL Integration, don't forget to add your OpenAI API key to your environment variables with the name OPENAI_API_KEY.

(lemming) user:~$ export OPENAI_API_KEY=<your_openai_api_key>

Start the Lemming Server

The Swagger page will show up at http://localhost:8000/docs. The OpenAPI spec can be obtained from the swagger page.

(lemming) user:~$ python -m uvicorn main:app --reload

Start the Lemming Client

user:~$ yarn install
user:~$ yarn start

Contributing

Contributions are welcome! 🤗 For instructions on setting up, go here.

You can install dev dependencies with:

(lemming) user:~$ pip install -e ".[dev]"

Citing our work

ICAPS 2023 Demonstration

download

@inproceedings{lemming,
title={{Lemming: A Guided Disambiguation Tool for Plan Selection}},
author={Jungkoo Kang and Tathagata Chakraborti and Michael Katz and Shirin Sohrabi and Francesco Fuggitti},
booktitle={ICAPS System Demonstration Track},
year={2023}}