Getting Started

Installing

L2P can be installed with pip:

pip install l2p

Using L2P

First things first, import the whole L2P library, or necessary modules (see L2P):

from l2p import *
# OR
from l2p import DomainBuilder, TaskBuilder, PromptBuilder, FeedbackBuilder

# util functions
from l2p.utils import *

L2P requires access to an LLM. Set up your LLM class and methods using the abstract BaseLLM(ABC) class. In this case, we have set up OpenAI’s models to our library for quickstart.

export OPENAI_API_KEY='YOUR-KEY' # e.g. OPENAI_API_KEY='sk-123456'
engine = "gpt-4o-mini"
api_key = os.environ.get('OPENAI_API_KEY')
openai_llm = OPENAI(model=engine, api_key=api_key)

Users can pass any prompt into their LLMs–as long as the structured output prompt follows the respective function (see Templates). We recommend using the PromptBuilder class that help organize prompts. This is a simple example:

from l2p.prompt_builder import PromptBuilder
prompt_builder = PromptBuilder()

role_desc = "Your role is to..."
format_desc = "You must follow this format..."
ex_desc = "Here is an example..."
task_desc = "{PLACEHOLDER}"

prompt = PromptBuilder(
    role = role_desc,
    format = format_desc,
    examples = [ex_desc],
    task = task_desc
)

print(prompt.generate_prompt())

Generated prompt:

[ROLE]: Your role is to...

------------------------------------------------
[FORMAT]: You must follow this format...

------------------------------------------------
[EXAMPLE(S)]:
Example 1:
Here is an example...

------------------------------------------------
[TASK]:
Here is the task to solve:
{PLACEHOLDER}

Build PDDL domain components using the DomainBuilder class. This is an example of extracting PDDL types using PromptBuilder:

import os
from l2p.domain_builder import DomainBuilder
from l2p.prompt_builder import PromptBuilder
from l2p.llm.openai import OPENAI
from l2p.utils import format_types, load_file

api_key = os.environ.get('OPENAI_API_KEY')
gpt_4o_mini = OPENAI(model="gpt-4o-mini", api_key=api_key)

domain_builder = DomainBuilder()
types_prompt = PromptBuilder(
    role="You are a PDDL assistant that is helping me design :types.",
    format=load_file("templates/domain_templates/formalize_type.txt"),
    task="{domain_desc}"
)

domain_desc = "The AI agent here is a mechanical robot arm that can pick and " \
    "place the blocks. Only one block may be moved at a time: it may either " \
    "be placed on the table or placed atop another block. Because of this, " \
    "any blocks that are, at a given time, under another block cannot be moved."

# extract types via LLM
types, llm_output, validation_info = domain_builder.formalize_types(
    model=gpt_4o_mini,
    domain_desc=domain_desc,
    prompt_template=types_prompt.generate_prompt()
    )

# print out types
print(format_types(types=types))

Generated types output:

{
    'block': '; A physical object that can be picked up and moved by the robot arm.',
    'table': '; A flat surface where blocks can be placed.',
    'robot_arm': '; The mechanical device capable of picking and placing blocks.'
}

Build PDDL problem components using the TaskBuilder class. This is an example of extracting PDDL initial states:

import os
from l2p.task_builder import TaskBuilder
from l2p.prompt_builder import PromptBuilder
from l2p.llm.openai import OPENAI
from l2p.utils import format_initial, load_file

api_key = os.environ.get('OPENAI_API_KEY')
gpt_4o_mini = OPENAI(model="gpt-4o-mini", api_key=api_key)

task_builder = TaskBuilder()
init_prompt = PromptBuilder(
    role="You are a PDDL assistant that is helping me design :init problems",
    format=load_file("templates/task_templates/formalize_initial.txt"),
    task="{problem_desc}"
)

problem_desc = "There are four blocks currently. The blue block is on the red " \
    "which is on the yellow. The yellow and the green are on the table. I want " \
    "the red on top of the green."

initial_states, llm_output, validation_info = task_builder.formalize_initial_state(
    model = gpt_4o_mini,
    problem_desc = problem_desc,
    prompt_template = init_prompt.generate_prompt()
)

print(format_initial(initial_states=initial_states))

Generated initial states:

(on blue red)
(on red yellow)
(on yellow table)
(on green table)

Build LLM feedback components using the FeedbackBuilder class. This is an example of getting LLM feedback from types:

import os
from l2p.feedback_builder import FeedbackBuilder
from l2p.prompt_builder import PromptBuilder
from l2p.llm.openai import OPENAI
from l2p.utils import load_file

api_key = os.environ.get('OPENAI_API_KEY')
gpt_4o_mini = OPENAI(model="gpt-4o-mini", api_key=api_key)

domain_desc = "The AI agent here is a mechanical robot arm that can pick and " \
        "place the blocks. Only one block may be moved at a time: it may either " \
        "be placed on the table or placed atop another block. Because of this, " \
        "any blocks that are, at a given time, under another block cannot be moved."

types = {
    'block': '; A physical object that can be picked up and moved by the robot arm.',
    'table': '; A flat surface where blocks can be placed.',
    'robot_arm': '; The mechanical device capable of picking and placing blocks.',
    'carpet': '; a carpet for a room.' # unnecessary type for domain
    }

feedback_builder = FeedbackBuilder()

feedback_prompt = PromptBuilder(
    role="You are a PDDL assistant that is providing feedback to :types.",
    format=load_file("templates/feedback_templates/feedback.txt"),
    task="{domain_desc} \n\n##Types\n{types}"
)

no_feedback, llm_output = feedback_builder.type_feedback(
    model = gpt_4o_mini,
    domain_desc = domain_desc,
    feedback_template = feedback_prompt.generate_prompt(),
    feedback_type = "llm",
    types=types
)

print(no_feedback, llm_output)

Generated feedback:

[NO FEEDBACK]: False

[LLM OUTPUT]
### JUDGMENT
```
The type "carpet" seems unnecessary in the context of the task, as it does not relate to the actions of picking and placing blocks. Consider removing it to maintain focus on relevant types.
```

Below are actual runnable usage examples. This is the general setup to build domain predicates:

import os
from l2p.domain_builder import DomainBuilder
from l2p.llm.openai import OPENAI
from l2p.utils import format_expression, load_file

domain_builder = DomainBuilder()

api_key = os.environ.get('OPENAI_API_KEY')
gpt_4o_mini = OPENAI(model="gpt-4o-mini", api_key=api_key)

# retrieve prompt information
base_path='tests/usage/prompts/domain/'
domain_desc = load_file(f'{base_path}blocksworld_domain.txt')
predicates_prompt = load_file(f'{base_path}formalize_predicates.txt')
types = load_file(f'{base_path}types.json')
action = load_file(f'{base_path}action.json')

# extract predicates via LLM
predicates, llm_output, validation_info = domain_builder.formalize_predicates(
    model=gpt_4o_mini,
    domain_desc=domain_desc,
    prompt_template=predicates_prompt,
    types=types
    )

# format key info into PDDL strings
predicate_str = "\n".join([pred["raw"].replace(":", " ; ") for pred in predicates])

print(f"PDDL domain predicates:\n{predicate_str}")

The following output is:

PDDL domain predicates:
- (holding ?a - arm ?b - block) ;  true if the arm ?a is currently holding the block ?b
- (on_table ?b - block) ;  true if the block ?b is on the table
- (clear ?b - block) ;  true if the block ?b is clear (no block on top of it)
- (on_top ?b1 - block ?b2 - block) ;  true if the block ?b1 is on top of the block ?b2

Here is how you would setup a PDDL problem:

import os
from l2p.llm.openai import OPENAI
from l2p.utils.pddl_types import Predicate
from l2p.task_builder import TaskBuilder
from l2p.utils import load_file

task_builder = TaskBuilder() # initialize task builder class

api_key = os.environ.get('OPENAI_API_KEY')
llm = OPENAI(model="gpt-4o-mini", api_key=api_key)

# load in assumptions
problem_desc = load_file(r'tests/usage/prompts/problem/blocksworld_problem.txt')
task_prompt = load_file(r'tests/usage/prompts/problem/formalize_task.txt')
types = load_file(r'tests/usage/prompts/domain/types.json')
predicates_json = load_file(r'tests/usage/prompts/domain/predicates.json')
predicates: list[Predicate] = [Predicate(**item) for item in predicates_json]

# extract PDDL task specifications via LLM
objects, init, goal, llm_response, validation_info = task_builder.formalize_task(
    model=llm,
    problem_desc=problem_desc,
    prompt_template=task_prompt,
    types=types,
    predicates=predicates
    )

# generate task file
pddl_problem = task_builder.generate_task(
    domain_name="blocksworld",
    problem_name="blocksworld_problem",
    objects=objects,
    initial=init,
    goal=goal)

print(f"PDDL problem:\n{pddl_problem}")

The following output is:

PDDL problem:
(define
    (problem blocksworld_problem)
    (:domain blocksworld)

    (:objects
        blue_block - block
        red_block - block
        yellow_block - block
        green_block - block
        table1 - table
    )

    (:init
        (on_top blue_block red_block)
        (on_top red_block yellow_block)
        (on_table yellow_block)
        (on_table green_block)
        (clear blue_block)
        (clear green_block)
    )

    (:goal
        (and
            (on_top red_block green_block)
            (clear green_block)
        )
    )
)

*IMPORTANT* It is highly recommended to use the base template found in Templates in your final prompt to properly extract LLM output into the designated Python formats from these methods.