CLMASP

CLMASP couples Large Language Models (LLMs) with Answer Set Programming (ASP) for executable robotic task planning in VirtualHome.

This repository contains the code for:

Improving Efficiency of Answer Set Planning with Rough Solutions from Large Language Models for Robotic Task Planning

The current code path is clingo-only. Older DLV/DLV2-specific files and commands have been removed.

Repository layout

CLMASP/
├── code/
│   ├── prepare_data/        # Raw VirtualHome data -> processed graphs / ASP facts / ChromaDB
│   └── clmasp/              # LLM rough plans + ASP refinement + evaluation helpers
├── configs/
│   └── local.env.example    # Copy to local.env for private keys and machine paths
├── scripts/
│   ├── env.sh               # Shared path/model/workflow configuration
│   ├── prepare_data.sh      # End-to-end data preparation
│   └── run_workflow.sh      # LLM generation + clingo ASP refinement
├── environment.yml
├── requirements.txt
└── README.md

Generated data, ChromaDB files, workflow outputs, logs, and local secrets are ignored by git.

This public repository intentionally does not vendor the VirtualHome simulator, VirtualHome raw programs, generated datasets, ChromaDB indexes, or workflow outputs. Follow the setup steps below to recreate them locally.

1. Installation

Create the conda environment:

conda env create -f environment.yml
conda activate clmasp

Or install manually:

conda create -n clmasp -c conda-forge clingo python=3.10
conda activate clmasp
pip install -r requirements.txt

2. VirtualHome simulator

This project uses the VirtualHome simulator. Place simulation/ and resources/ at the repository root:

git clone https://github.com/xavierpuigf/virtualhome.git
cd virtualhome
git checkout 58970fd80951c2eaa1af713e0917d1a105353ad8
cd ..
cp -r virtualhome/simulation ./simulation
cp -r virtualhome/resources ./resources

The original VirtualHome version may need the following compatibility fixes:

• In simulation/evolving_graph/execution.py, change:

  return _walk_find_executor.execute(script, state, info, char_index, modify, in_place)

  to:

  return _walk_find_executor.execute(script, state, info, char_index)

• In WalkExecutor, _FindExecutor, and FindExecutor, add an object-found guard after object lookup:

  if current_obj is None:
      info.object_found_error()

• In WalkExecutor, FindExecutor, and _FindExecutor, add a node guard after _get_room_node(...):

  if not hasattr(node, "id"):
      info.object_found_error()

• Around call_action_method(...), catch simulator exceptions and return the previous state:

  try:
      state = next(self.call_action_method(future_script, state, info, self.char_index), None)
  except Exception as e:
      info.error(e)
      return False, prev_state, graph_state_list

After this step the root directory should contain:

CLMASP/
├── code/
├── dataset/
├── resources/
├── simulation/
└── README.md

3. Configure local settings

Create a private local config file:

cp configs/local.env.example configs/local.env

configs/local.env is ignored by git. Put API keys and machine-specific paths there rather than in scripts or notebooks.

Edit configs/local.env:

export OPENAI_API_KEY="<your_api_key>"
# export OPENAI_BASE_URL="https://your-compatible-endpoint/v1"

# Use a local path on offline servers, or a Hugging Face model id if network is available.
export CLMASP_EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2"
export CLMASP_LLM_VERSION="gpt-3.5-turbo"
export CLMASP_ITER_NAME="workflow"

Then load the shared configuration:

source scripts/env.sh

scripts/env.sh defines the common paths used by all examples:

• DATA_ROOT
• RAW_ROOT
• PROC_ROOT
• WORKFLOW_ROOT
• MODEL_NAME_OR_PATH
• LLM_VERSION

4. Download raw VirtualHome programs

mkdir -p dataset
cd dataset
wget http://virtual-home.org/release/programs/programs_processed_precond_nograb_morepreconds.zip
mkdir -p rawdata
unzip programs_processed_precond_nograb_morepreconds.zip -d rawdata/
rm programs_processed_precond_nograb_morepreconds.zip
cd ..

The raw programs should now be under:

dataset/rawdata/programs_processed_precond_nograb_morepreconds/

5. Prepare data

Run the full preparation pipeline:

source scripts/env.sh
bash scripts/prepare_data.sh

This creates:

• executable task JSONs in ${PROC_ROOT}/exec100data and ${PROC_ROOT}/exec100data_onetime
• processed init/final graphs in ${PROC_ROOT}/processed_init_and_final_graphs
• ASP facts in ${PROC_ROOT}/env2lp
• ChromaDB embeddings in ${PROC_ROOT}/embeddings/chromadb_storage

Equivalent manual commands:

python code/prepare_data/t1_filter_exec_and_build_graphs.py \
  --rawdata_dir "${RAW_ROOT}" \
  --output_actions_dir "${PROC_ROOT}/${PROC_ACTIONS_ALL_DIRNAME}" \
  --output_actions_onetime_dir "${PROC_ROOT}/${PROC_ACTIONS_ONETIME_DIRNAME}" \
  --output_graph_dir "${PROC_ROOT}/${PROC_GRAPH_DIRNAME}" \
  --max_workers "${CLMASP_MAX_WORKERS}"

python code/prepare_data/t2_env2asp.py \
  --input_graph_dir "${PROC_ROOT}/${PROC_GRAPH_DIRNAME}" \
  --output_lp_dir "${PROC_ROOT}/env2lp"

python code/prepare_data/t3_create_db.py \
  --input_graph_dir "${PROC_ROOT}/${PROC_GRAPH_DIRNAME}" \
  --output_dir "${PROC_ROOT}/${PROC_EMBEDDING_DIRNAME}" \
  --chromadb_dir "${PROC_ROOT}/${PROC_EMBEDDING_DIRNAME}/${CHROMADB_DIRNAME}" \
  --obj_collection_name "${EMBEDDINGofOBJS}" \
  --action_collection_name "${EMBEDDINGofACTIONS}" \
  --embedding_model "${MODEL_NAME_OR_PATH}" \
  --reconstruct

6. Run CLMASP

Run LLM rough-plan generation followed by clingo ASP refinement:

source scripts/env.sh
bash scripts/run_workflow.sh

Outputs are written under:

${WORKFLOW_ROOT}/${LLM_VERSION}/LLM/
${WORKFLOW_ROOT}/${LLM_VERSION}/ASP/

Equivalent manual commands:

python code/clmasp/t1_llm_generate_rough_plans.py \
  --exec_programs_dir "${PROC_ROOT}/${PROC_ACTIONS_ONETIME_DIRNAME}" \
  --graph_dir "${PROC_ROOT}/${PROC_GRAPH_DIRNAME}" \
  --output_root "${WORKFLOW_ROOT}" \
  --overwrite \
  --llm_versions "${LLM_VERSION}" \
  --chromadb_dir "${PROC_ROOT}/${PROC_EMBEDDING_DIRNAME}/${CHROMADB_DIRNAME}" \
  --obj_collection_name "${EMBEDDINGofOBJS}" \
  --action_collection_name "${EMBEDDINGofACTIONS}" \
  --embedding_model "${MODEL_NAME_OR_PATH}"

python code/clmasp/t2_asp_refine_plans.py \
  --llm_output_root "${WORKFLOW_ROOT}" \
  --llm_version "${LLM_VERSION}" \
  --graph_dir "${PROC_ROOT}/${PROC_GRAPH_DIRNAME}" \
  --env2lp_dir "${PROC_ROOT}/env2lp" \
  --solve_lp_out_dir "${WORKFLOW_ROOT}/tmp_solve_lp" \
  --lp_dir "code/clmasp/lp" \
  --output_root "${WORKFLOW_ROOT}" \
  --solver clingo \
  --time_limit "${CLMASP_ASP_TIME_LIMIT}" \
  --overwrite

For sharded ASP refinement:

source scripts/env.sh
SHARD_MOD=8 TIME_LIMIT=600 bash code/clmasp/t2_asp_run.sh

7. Evaluation helpers

Single-ground-truth and multi-ground-truth evaluation helpers are available in:

python code/clmasp/t3_eval_clmasp.py --iteration_name <name> --data_type ASPs-new-converter
python code/clmasp/t3_eval_clmasp_multi_GT.py \
  --iteration_name <name> \
  --data_type ASPs-new-converter \
  --multi_gt_json <path/to/taskname_steps_and_filepath.json>

These scripts preserve the original experiment layout and may need path adjustments if your workflow outputs are stored somewhere other than the legacy output-folder/ layout.

Citation

If you found this work useful, please cite:

@inproceedings{ijcai2025p509,
  title     = {Improving Efficiency of Answer Set Planning with Rough Solutions from Large Language Models for Robotic Task Planning},
  author    = {Lin, Xinrui and Wu, Yangfan and Yang, Huanyu and Huang, Yuting and Zhang, Yu and Ji, Jianmin and Zhang, Yanyong},
  booktitle = {Proceedings of the Thirty-Fourth International Joint Conference on
               Artificial Intelligence, {IJCAI-25}},
  publisher = {International Joint Conferences on Artificial Intelligence Organization},
  editor    = {James Kwok},
  pages     = {4570--4578},
  year      = {2025},
  month     = {8},
  note      = {Main Track},
  doi       = {10.24963/ijcai.2025/509},
  url       = {https://doi.org/10.24963/ijcai.2025/509},
}