[![CC BY-NC-SA 4.0][cc-by-nc-sa-shield]][cc-by-nc-sa]
[](https://pypi.org/project/latent-explorer)
[](https://github.com/Ipazia-AI/latent-explorer/releases)
[](https://github.com/Ipazia-AI)
[](
https://doi.org/10.48550/arXiv.2404.03623)
Latent-Explorer is the Python implementation of the framework proposed in the paper [*Unveiling LLMs: The Evolution of Latent Representations in a Dynamic Knowledge Graph*](https://arxiv.org/abs/2404.03623) to appear in the 1<sup>st</sup> [Conference of Language Modeling](https://colmweb.org/index.html) (COLM).
## Overview
This framework decodes factual knowledge embedded in token representations from a vector space into a set of ground predicates, exhibiting its layer-wise evolution through a dynamic knowledge graph.
It employs separate model inferences, with the technique of activation patching, to interpret the semantics embedded within the latent representations of the original inference.
This framework can be employed to study the vector space of LLMs to address several research questions, including:
(i) which factual knowledge LLMs use in claim verification,
(ii) how this knowledge evolves throughout the model's inference, and
(iii) whether any distinctive patterns exist in this evolution.
## Installation
Use the package manager [pip](https://pip.pypa.io/en/stable/) to install the Python package
```bash
pip install latent-explorer
```
or download the [repository](https://github.com/Ipazia-AI/latent-explorer) and install the package with
` pip install -e . `
## Demo
The folder `tutorial` includes a script showcasing the pipeline [`tutorial/script.py`](./tutorial/script.py)
## Usage
### Import the package
```python
import latent_explorer
```
### Initialize the application with the LLM and the inputs
```python
explorer = latent_explorer.LatentExplorer(
model_name = "meta-llama/llama-2-7b-chat-hf",
inputs = ["The capital of France is Paris"]
)
```
### Prepare the textual prompts
```python
explorer.generate_prompts(verbose = True)
```
### Perform the inference and get the hidden states
```python
explorer.inference(parse_output = True, output_hidden_states = True)
```
### Probe each hidden states
```python
results = explorer.probe_hidden_states()
```
### Save the textual results
```python
latent_explorer.utils.save_results(results, folder_path = "outputs")
```
### Generate the dynamic knowledge graphs
```python
tg = latent_explorer.TempoGrapher(results)
```
### Get the graphs
```python
graphs = tg.get_graphs()
```
### Generate and save the graphical figures
```python
tg.save_graphs(folder_path = "outputs")
```
## Language models available
This package inherits all of the LLMs supported by the [LitGPT](https://github.com/Lightning-AI/litgpt/blob/main/tutorials/download_model_weights.md) package.
This framework works with instruction-tuned language models, such as those named with the suffixes "inst", "instruct", or "chat".
```python
models = latent_explorer.utils.all_supported_models()
```
## Computational resources
Since this framework performs multiple language model inferences, using a GPU is recommended ([see CUDA](https://docs.nvidia.com/cuda/cuda-quick-start-guide/index.html)). This framework has been tested with using two GPU-based configurations: (1x) *NVIDIA® A100-40GB*, and (4x) *NVIDIA® T4 Tensor Core - 16GB*.
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
## Acknowledgements
This implementation is powered by [LitGPT](https://github.com/Lightning-AI/litgpt), conceptualised, designed and developed by [Marco Bronzini](https://www.linkedin.com/in/bronzinimarco).
This work has been funded by [Ipazia S.p.A.](https://ipazia.com)
## Citation
If you use this package or its code in your research, please cite the following work:
```bibtex
@inproceedings{bronzini2024unveiling,
title = {Unveiling LLMs: The evolution of latent representations in a dynamic knowledge graph},
author = {Bronzini, Marco and Nicolini, Carlo and Lepri, Bruno and Staiano, Jacopo and Passerini, Andrea},
booktitle = {First Conference on Language Modeling},
year = {2024},
url = {https://openreview.net/forum?id=dWYRjT501w}
}
```
## License
This work is licensed under a
[Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License][cc-by-nc-sa].
[![CC BY-NC-SA 4.0][cc-by-nc-sa-image]][cc-by-nc-sa]
[cc-by-nc-sa]: http://creativecommons.org/licenses/by-nc-sa/4.0
[cc-by-nc-sa-image]: https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png
[cc-by-nc-sa-shield]: https://img.shields.io/badge/license-CC%20BY--NC--SA%204.0-lightgrey.svg
Raw data
{
"_id": null,
"home_page": null,
"name": "latent-explorer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Marco Bronzini <m.bronzini@ipazia.com>",
"keywords": "Large Language Models, Latent Representations, Graphs, Factual Knowledge, Activation Patching, Probes, Residual Stream",
"author": "Ipazia AI",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/14/a0/c9e55dae5041644f34fb862c053893a613190752ba3dff9a6ea027faec27/latent_explorer-0.1.5.tar.gz",
"platform": null,
"description": "\r\n\r\n[![CC BY-NC-SA 4.0][cc-by-nc-sa-shield]][cc-by-nc-sa]\r\n[](https://pypi.org/project/latent-explorer)\r\n[](https://github.com/Ipazia-AI/latent-explorer/releases)\r\n[](https://github.com/Ipazia-AI)\r\n[](\r\nhttps://doi.org/10.48550/arXiv.2404.03623)\r\n\r\n\r\nLatent-Explorer is the Python implementation of the framework proposed in the paper [*Unveiling LLMs: The Evolution of Latent Representations in a Dynamic Knowledge Graph*](https://arxiv.org/abs/2404.03623) to appear in the 1<sup>st</sup> [Conference of Language Modeling](https://colmweb.org/index.html) (COLM).\r\n\r\n## Overview\r\nThis framework decodes factual knowledge embedded in token representations from a vector space into a set of ground predicates, exhibiting its layer-wise evolution through a dynamic knowledge graph. \r\nIt employs separate model inferences, with the technique of activation patching, to interpret the semantics embedded within the latent representations of the original inference.\r\nThis framework can be employed to study the vector space of LLMs to address several research questions, including:\r\n(i) which factual knowledge LLMs use in claim verification,\r\n(ii) how this knowledge evolves throughout the model's inference, and\r\n(iii) whether any distinctive patterns exist in this evolution.\r\n\r\n\r\n\r\n\r\n\r\n\r\n## Installation\r\nUse the package manager [pip](https://pip.pypa.io/en/stable/) to install the Python package\r\n\r\n```bash\r\npip install latent-explorer\r\n```\r\n\r\nor download the [repository](https://github.com/Ipazia-AI/latent-explorer) and install the package with \r\n` pip install -e . `\r\n\r\n## Demo\r\nThe folder `tutorial` includes a script showcasing the pipeline [`tutorial/script.py`](./tutorial/script.py)\r\n\r\n## Usage\r\n\r\n### Import the package\r\n```python\r\nimport latent_explorer\r\n```\r\n\r\n### Initialize the application with the LLM and the inputs\r\n```python\r\nexplorer = latent_explorer.LatentExplorer(\r\n model_name = \"meta-llama/llama-2-7b-chat-hf\", \r\n inputs = [\"The capital of France is Paris\"]\r\n)\r\n```\r\n### Prepare the textual prompts\r\n```python\r\nexplorer.generate_prompts(verbose = True)\r\n```\r\n\r\n### Perform the inference and get the hidden states\r\n```python\r\nexplorer.inference(parse_output = True, output_hidden_states = True)\r\n```\r\n\r\n### Probe each hidden states\r\n```python\r\nresults = explorer.probe_hidden_states()\r\n```\r\n\r\n### Save the textual results\r\n```python\r\nlatent_explorer.utils.save_results(results, folder_path = \"outputs\")\r\n```\r\n\r\n### Generate the dynamic knowledge graphs\r\n```python\r\ntg = latent_explorer.TempoGrapher(results)\r\n```\r\n\r\n### Get the graphs\r\n```python\r\ngraphs = tg.get_graphs()\r\n```\r\n\r\n### Generate and save the graphical figures\r\n```python\r\ntg.save_graphs(folder_path = \"outputs\")\r\n```\r\n\r\n## Language models available\r\nThis package inherits all of the LLMs supported by the [LitGPT](https://github.com/Lightning-AI/litgpt/blob/main/tutorials/download_model_weights.md) package.\r\nThis framework works with instruction-tuned language models, such as those named with the suffixes \"inst\", \"instruct\", or \"chat\". \r\n\r\n```python\r\nmodels = latent_explorer.utils.all_supported_models()\r\n```\r\n\r\n## Computational resources\r\nSince this framework performs multiple language model inferences, using a GPU is recommended ([see CUDA](https://docs.nvidia.com/cuda/cuda-quick-start-guide/index.html)). This framework has been tested with using two GPU-based configurations: (1x) *NVIDIA\u00ae A100-40GB*, and (4x) *NVIDIA\u00ae T4 Tensor Core - 16GB*. \r\n\r\n## Contributing\r\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\r\n\r\n## Acknowledgements\r\nThis implementation is powered by [LitGPT](https://github.com/Lightning-AI/litgpt), conceptualised, designed and developed by [Marco Bronzini](https://www.linkedin.com/in/bronzinimarco).\r\nThis work has been funded by [Ipazia S.p.A.](https://ipazia.com)\r\n\r\n## Citation\r\nIf you use this package or its code in your research, please cite the following work:\r\n\r\n```bibtex\r\n@inproceedings{bronzini2024unveiling,\r\n title = {Unveiling LLMs: The evolution of latent representations in a dynamic knowledge graph},\r\n author = {Bronzini, Marco and Nicolini, Carlo and Lepri, Bruno and Staiano, Jacopo and Passerini, Andrea},\r\n booktitle = {First Conference on Language Modeling},\r\n year = {2024},\r\n url = {https://openreview.net/forum?id=dWYRjT501w}\r\n}\r\n```\r\n\r\n## License\r\nThis work is licensed under a\r\n[Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License][cc-by-nc-sa].\r\n\r\n[![CC BY-NC-SA 4.0][cc-by-nc-sa-image]][cc-by-nc-sa]\r\n\r\n[cc-by-nc-sa]: http://creativecommons.org/licenses/by-nc-sa/4.0\r\n[cc-by-nc-sa-image]: https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png\r\n[cc-by-nc-sa-shield]: https://img.shields.io/badge/license-CC%20BY--NC--SA%204.0-lightgrey.svg\r\n",
"bugtrack_url": null,
"license": "CC BY-NC-SA 4.0",
"summary": "A Python library based on the technique of activation patching to represent the factual knowledge encoded in the latent space of large language models as dynamic knowledge graphs.",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/Ipazia-AI",
"Repository": "https://github.com/Ipazia-AI/latent-explorer"
},
"split_keywords": [
"large language models",
" latent representations",
" graphs",
" factual knowledge",
" activation patching",
" probes",
" residual stream"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8c70ef5c537f23b06d49d38dc837530aa1b616e1b4e53ca5e41b762de0aac5ae",
"md5": "670da656b8ef145519731f09468ee901",
"sha256": "7b40a101322709c5b1280ca519f4723636bedc1aab6f04b6848c87474a0f8778"
},
"downloads": -1,
"filename": "latent_explorer-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "670da656b8ef145519731f09468ee901",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 34743,
"upload_time": "2024-10-21T12:58:13",
"upload_time_iso_8601": "2024-10-21T12:58:13.203362Z",
"url": "https://files.pythonhosted.org/packages/8c/70/ef5c537f23b06d49d38dc837530aa1b616e1b4e53ca5e41b762de0aac5ae/latent_explorer-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "14a0c9e55dae5041644f34fb862c053893a613190752ba3dff9a6ea027faec27",
"md5": "ae8d4bb8f396f39250748fabba013c9c",
"sha256": "e84ebce808b655b37f35e21fc1a1bbb0386e4f37c991ced7025af88f104ce54d"
},
"downloads": -1,
"filename": "latent_explorer-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "ae8d4bb8f396f39250748fabba013c9c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 2047772,
"upload_time": "2024-10-21T12:58:16",
"upload_time_iso_8601": "2024-10-21T12:58:16.635435Z",
"url": "https://files.pythonhosted.org/packages/14/a0/c9e55dae5041644f34fb862c053893a613190752ba3dff9a6ea027faec27/latent_explorer-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 12:58:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Ipazia-AI",
"github_project": "latent-explorer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "latent-explorer"
}
JSON
