Authors: Pedro Valois, Lincon Souza, Erica Kido Shimomoto, Kazuhiro Fukui

The Frame Representation Hypothesis is a robust framework for understanding and controlling LLMs. We use WordNet to generate concepts that can both guide the model text generation and expose biases or vulnerabilities.

• ♻️ Capable of dealing with multi-token words.

• 🎧 Can use OMW 50M word dataset to build 100,000 concepts.

• 💪 Tested on Llama 3.1, Gemma 2 and Phi 3 ensuring high-quality responses.

• 🚀 Very fast and low memory cost. Able to compute all concepts in less than a second and fit both Llama 3.1 8B Instruct and Concepts in a RTX 4090 GPU.

1. Clone this repository.

git clone https://github.com/Pedrexus/frame-representation-hypothesis
cd frame-representation-hypothesis

2. Install packages.

pip install -U pip
pip install uv
uv sync

• We also provide a Docker image (you may need to update the CUDA version to yours)

3. Add Environment Variables

• Create a .env file following the .env.example file.
• You will need a Hugging Face Acces Token to Download models. Here is how to obtain it: https://huggingface.co/docs/hub/en/security-tokens
• You will also need to ask for permission to download each model in models.yaml: https://huggingface.co/docs/hub/en/models-gated - hugging-quants/Meta-Llama-3.1-8B-Instruct-AWQ-INT4 - meta-llama/Meta-Llama-3.1-8B - ...

4. Download Models

Run 01_START_HERE.ipynb to download all models.

Each experiment in the paper is in one of the jupyter notebooks starting from 02.

Our code is released under the MIT License.

If you have any questions, please feel free to submit an issue or contact pedro@cvlab.cs.tsukuba.ac.jp.

If our work is useful for you, please cite as:

@article{valois2025framerepresentationhypothesis,
      title={Frame Representation Hypothesis: Multi-Token LLM Interpretability and Concept-Guided Text Generation},
      author={Pedro H. V. Valois and Lincon S. Souza and Erica K. Shimomoto and Kazuhiro Fukui},
      journal = {Transactions of the Association for Computational Linguistics},
      year={2025},
      url={https://arxiv.org/abs/2412.07334},
}