interact

Official Implementation for the intelligibility protocol, PXP. The theory paper was accepted to the Machine Learning Journal [DoI] and the implementation was accepted to the First Workshop on Multi-Turn Interactions in Large Language Models at NeurIPS 2025.

Installation

We have very minimal dependencies, and you can install them using the following command:

pip install -r requirements.txt

You might want to create a virtual environment (or use conda) to avoid conflicts with your system packages. We use python3.9.18 for all experiments.

You will also have to create a results folder,

mkdir results

Finally, you can place your API keys in a .env file in the root directory, a template is in .env.template.

Data

Our data is provided as a zip file, data.zip, run

unzip data.zip

to extract the data. You can then use src/preprocess.py to generate the data in the correct format, for the experiments. This will also summarize the data, using the summarize function from src/utils.py.

Reproducing our results (simulation)

To reproduce our RAD results, you can run the following command:

python src/interact.py --num_iter=5 --machine="claude-3-5-sonnet-20240620" --human_type static

To reproduce our DRUG results, you can run the following command:

python src/interact.py --num_iter=5 --machine="claude-3-5-sonnet-20240620" --task=DRUG --human_type=static --eval_at_start

This will output the counts of one-way and two-way intelligible sessions, create a tags.txt file of the actual tags exchanged between the two agents and also save the D (data.pkl), M (messages.pkl) and C (context.pkl) (from Procedure 1 in the paper) to the results/ folder. To reproduce the trend in Figure 3 from the paper, we ran the above command 5 times and manually extracted the number of strong and ultra-strong intelligible sessions (upto an interaction limit) were generated per agent.

Reproducing our results (live interaction)

Reproducing the DRUG-Human results requires an expert and so the outcome may be stochastic, but an experiment can be launched using:

python src/interact.py --num_iter=5 --machine="claude-3-sonnet-20240229" --task=DRUG --no_learn

More information

Customizable parameters

Please run python src/interact.py --help to see all the parameters that can be customized, we support several LLMs, and the implementation should ideally run with all LLMs supported by litellm.

Resuming a failed experiment

If the experiment crashes in between (due to API limits, or wrong input, etc.) you can resume the experiment by passing the --resume flag. The -h flag describes a group of arguments that need to be passed when this flag is set (path to the ongoing context, messages, metrics, etc. files, these are all saved by the code automatically).

Static / Real-time feedback

In general the code allows for interaction between both static and real-time human feedback and an LLM (interfaced by the XMachine). To use the approach with custom data,

• you can use some form of static human feedback stored in data as a CSV,
• as with the human experiments, one can use the command line and a real expert human for feedback.
• DRUG can also be run in static mode by passing --human_type=static

How to use the code for a different task

Here, we precisely describe how to use the code for a different task, say MATS (Materials Science).

• Decide the type of feedback you have access to, static (CSV with some predictions and explanations) or real-time (human expert)
• If it is static then you would need to add the data to the data/ folder.
• Now, depeding on the type of feedback, you should implement a MATSAgent class in src/agents.py which should inherit from Agent.
• Following this, implement MATSMachine and MATSHuman classes in the same file, to see the differences in real-time / static feedback, you can look at DRUGHuman and DRUGHumanStatic.
• With this, you need to change the create_agent in src/agent.py to also be compatible with the new task.
• Finally, you have to implement the MATS class in src/tasks.py which should inherit from Task and borrow code from RAD and DRUG appropriately.
• Now, you can run the code using the following command: (add this task to the choices for the --task argument)

python src/interact.py --num_iter=5 --machine="claude-3-sonnet-20240229" --task=MATS

• We also provide a --debug flag, this will clip the train_data to 5 examples, and the val and test data to 2 examples each, this is useful for debugging.

Example

This is an example interaction (from the RAD task) generated by using the PXP protocol and our implementation (As explained in the paper, this is a special case of the protocol such that the human-agent can never revise it's internal model).

Please raise an issue if you have any questions or need help with the code!

Citation

For the theory

@Article{Baskar2025,
  author="Baskar, A.
  and Srinivasan, Ashwin
  and Bain, Michael
  and Coiera, Enrico",
  title="A model for intelligible interaction between agents that predict and explain",
  journal="Machine Learning",
  year="2025",
  month="Feb",
  day="20",
  volume="114",
  number="4",
  pages="97",
  issn="1573-0565",
  doi="10.1007/s10994-025-06750-z",
  url="https://doi.org/10.1007/s10994-025-06750-z"
}

For this implementation

@misc{mestha2025multiturnhumanllminteractionlens,
      title={Multi-Turn Human-LLM Interaction Through the Lens of a Two-Way Intelligibility Protocol}, 
      author={Harshvardhan Mestha and Karan Bania and Shreyas V Sathyanarayana and Sidong Liu and Ashwin Srinivasan},
      year={2025},
      eprint={2410.20600},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2410.20600}, 
}