# nnez
**Neural Network Easy Extraction** - A lightweight Python package for extracting activation patterns from transformer language models with just a few lines of code. The package caches your embeddings, so after you create your embedding for a piece of text once, the package will just quickly load that embedding in the future rather than recomputing it.
This is designed to be maximally simple and was originally meant to help in cases where you just want to create an embedding based on a text, which is a common usecase in cognitive neuroscience research. This package is built ontop of [NNsight](https://github.com/ndif-team/nnsight).
Below, I describe how to use the package. See also `examples/quickstart.py`. The example below uses "gpt2", which is quick to run, but its embeddings will be low quality. You may want to try a more recent model like "meta-llama/Llama-3.2-3B"
## 📦 Installation
```bash
pip install nnez
```
## 🎮 Quick Start
### Extract Activations from any Transformer LLM
```python
from nnez import get_activity_from_text
# Extract activations from specific layers of GPT-2
text = "The capital of France is Paris."
layers = [5, 10] # Extract from layers 5 and 10
activations = get_activity_from_text(
text=text,
layers_list=layers,
model_name="gpt2" # You can specify any huggingface model (e.g., "meta-llama/Llama-3.2-3B")
)
print(activations.shape) # (2, 768) - 2 layers, 768 dimensions each
```
### Single Layer Extraction
```python
# Extract from a single layer (returns 1D array)
act = get_activity_from_text("Hello world!", 11) # Layer 11 only
print(act.shape) # (768,) - Single layer, flattened
```
### Batch Processing
```python
import numpy as np
texts = ["First text", "Second text", "Third text"]
all_activations = []
for text in texts:
act = get_activity_from_text(text, [0, 6, 11])
all_activations.append(act)
# Stack into 3D array: (num_texts, num_layers, hidden_size)
batch_activations = np.stack(all_activations)
print(batch_activations.shape) # (3, 3, 768)
```
## Grammar Utilities
The package includes some grammar utilities leveraging the `inflect` library. These are helpful if you want to do an analysis like that in the associated LLM-RSA paper (Bogdan et al., under review).
```python
from nnez.grammar import get_article, pluralize, quantify
# Smart article detection
get_article("hour") # "an" (silent h)
get_article("university") # "a" (y-sound)
get_article("FBI") # "an" (eff-bee-eye)
# Pluralization
pluralize("child") # "children"
pluralize("analysis") # "analyses"
pluralize("octopus") # "octopuses"
# Quantification
quantify(0, "cat") # "no cats"
quantify(1, "child") # "1 child"
quantify(3, "child") # "3 children"
```
## 📊 Output Shape Reference
| Model | HuggingFace Name | Hidden Size | Output Shape (3 layers) |
|-------|------------------|------------|-------------------------|
| GPT-2 | `gpt2` | 768 | (3, 768) |
| Llama 3.2 3B | `meta-llama/Llama-3.2-3B` | 3072 | (3, 3072) |
| Llama 3.1 8B | `meta-llama/Llama-3.1-8B` | 4096 | (3, 4096) |
| Qwen 2.5 3B | `Qwen/Qwen2.5-3B` | 2048 | (3, 2048) |
| Qwen 2.5 7B | `Qwen/Qwen2.5-7B` | 3584 | (3, 3584) |
| Mistral 7B | `mistralai/Mistral-7B-v0.1` | 4096 | (3, 4096) |
| Gemma 2 2B | `google/gemma-2-2b` | 2304 | (3, 2304) |
| Phi-3 Mini | `microsoft/Phi-3-mini-4k-instruct` | 3072 | (3, 3072) |
| BERT Base | `bert-base-uncased` | 768 | (3, 768) |
| BERT Large | `bert-large-uncased` | 1024 | (3, 1024) |
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/nnez",
"name": "nnez",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "llm, transformers, activation-extraction, interpretability, neural-networks, nlp, machine-learning, deep-learning, gpt, bert, probing, residual-stream",
"author": "Your Name",
"author_email": "Paul Bogdan <paulcbogdan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/87/56/52a8ca050241d17deda6f8c0dfb7705890d6bb4f92f520a7fc470c5e8809/nnez-0.1.3.tar.gz",
"platform": null,
"description": "# nnez\r\n\r\n**Neural Network Easy Extraction** - A lightweight Python package for extracting activation patterns from transformer language models with just a few lines of code. The package caches your embeddings, so after you create your embedding for a piece of text once, the package will just quickly load that embedding in the future rather than recomputing it.\r\n\r\nThis is designed to be maximally simple and was originally meant to help in cases where you just want to create an embedding based on a text, which is a common usecase in cognitive neuroscience research. This package is built ontop of [NNsight](https://github.com/ndif-team/nnsight).\r\n\r\nBelow, I describe how to use the package. See also `examples/quickstart.py`. The example below uses \"gpt2\", which is quick to run, but its embeddings will be low quality. You may want to try a more recent model like \"meta-llama/Llama-3.2-3B\"\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\npip install nnez\r\n```\r\n\r\n## \ud83c\udfae Quick Start\r\n\r\n### Extract Activations from any Transformer LLM\r\n\r\n```python\r\nfrom nnez import get_activity_from_text\r\n\r\n# Extract activations from specific layers of GPT-2\r\ntext = \"The capital of France is Paris.\"\r\nlayers = [5, 10] # Extract from layers 5 and 10\r\n\r\nactivations = get_activity_from_text(\r\n text=text,\r\n layers_list=layers,\r\n model_name=\"gpt2\" # You can specify any huggingface model (e.g., \"meta-llama/Llama-3.2-3B\")\r\n)\r\n\r\nprint(activations.shape) # (2, 768) - 2 layers, 768 dimensions each\r\n```\r\n\r\n### Single Layer Extraction\r\n\r\n```python\r\n# Extract from a single layer (returns 1D array)\r\nact = get_activity_from_text(\"Hello world!\", 11) # Layer 11 only\r\nprint(act.shape) # (768,) - Single layer, flattened\r\n```\r\n\r\n### Batch Processing\r\n\r\n```python\r\nimport numpy as np\r\n\r\ntexts = [\"First text\", \"Second text\", \"Third text\"]\r\nall_activations = []\r\n\r\nfor text in texts:\r\n act = get_activity_from_text(text, [0, 6, 11])\r\n all_activations.append(act)\r\n\r\n# Stack into 3D array: (num_texts, num_layers, hidden_size)\r\nbatch_activations = np.stack(all_activations)\r\nprint(batch_activations.shape) # (3, 3, 768)\r\n```\r\n\r\n## Grammar Utilities\r\n\r\nThe package includes some grammar utilities leveraging the `inflect` library. These are helpful if you want to do an analysis like that in the associated LLM-RSA paper (Bogdan et al., under review).\r\n\r\n```python\r\nfrom nnez.grammar import get_article, pluralize, quantify\r\n\r\n# Smart article detection\r\nget_article(\"hour\") # \"an\" (silent h)\r\nget_article(\"university\") # \"a\" (y-sound)\r\nget_article(\"FBI\") # \"an\" (eff-bee-eye)\r\n\r\n# Pluralization\r\npluralize(\"child\") # \"children\"\r\npluralize(\"analysis\") # \"analyses\"\r\npluralize(\"octopus\") # \"octopuses\"\r\n\r\n# Quantification\r\nquantify(0, \"cat\") # \"no cats\"\r\nquantify(1, \"child\") # \"1 child\"\r\nquantify(3, \"child\") # \"3 children\"\r\n```\r\n\r\n## \ud83d\udcca Output Shape Reference\r\n\r\n| Model | HuggingFace Name | Hidden Size | Output Shape (3 layers) |\r\n|-------|------------------|------------|-------------------------|\r\n| GPT-2 | `gpt2` | 768 | (3, 768) |\r\n| Llama 3.2 3B | `meta-llama/Llama-3.2-3B` | 3072 | (3, 3072) |\r\n| Llama 3.1 8B | `meta-llama/Llama-3.1-8B` | 4096 | (3, 4096) |\r\n| Qwen 2.5 3B | `Qwen/Qwen2.5-3B` | 2048 | (3, 2048) |\r\n| Qwen 2.5 7B | `Qwen/Qwen2.5-7B` | 3584 | (3, 3584) |\r\n| Mistral 7B | `mistralai/Mistral-7B-v0.1` | 4096 | (3, 4096) |\r\n| Gemma 2 2B | `google/gemma-2-2b` | 2304 | (3, 2304) |\r\n| Phi-3 Mini | `microsoft/Phi-3-mini-4k-instruct` | 3072 | (3, 3072) |\r\n| BERT Base | `bert-base-uncased` | 768 | (3, 768) |\r\n| BERT Large | `bert-large-uncased` | 1024 | (3, 1024) |\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Neural Network Easy Extraction - Simple LLM activation extraction in one line",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/yourusername/nnez/issues",
"Changelog": "https://github.com/yourusername/nnez/blob/main/CHANGELOG.md",
"Documentation": "https://nnez.readthedocs.io/",
"Homepage": "https://github.com/yourusername/nnez",
"Repository": "https://github.com/yourusername/nnez.git"
},
"split_keywords": [
"llm",
" transformers",
" activation-extraction",
" interpretability",
" neural-networks",
" nlp",
" machine-learning",
" deep-learning",
" gpt",
" bert",
" probing",
" residual-stream"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "07bccf33c6000e15508f7517ec16149ab6e8894b3642207994a853d89e53045c",
"md5": "79826f5f291f8d059b56ca27adc7245e",
"sha256": "6a4f8fc28cc406b43ac6f66feaa2b184c2dd4a3cf2d3b081dc627a890ca06cb7"
},
"downloads": -1,
"filename": "nnez-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "79826f5f291f8d059b56ca27adc7245e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13778,
"upload_time": "2025-10-23T19:54:44",
"upload_time_iso_8601": "2025-10-23T19:54:44.021712Z",
"url": "https://files.pythonhosted.org/packages/07/bc/cf33c6000e15508f7517ec16149ab6e8894b3642207994a853d89e53045c/nnez-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "875652a8ca050241d17deda6f8c0dfb7705890d6bb4f92f520a7fc470c5e8809",
"md5": "5212a577e2ea3c7327e5d50dfbcee0bf",
"sha256": "c33de7d1f245faff810c26a3c650a495a9a744f51846aaf3eb43f33aea8fc517"
},
"downloads": -1,
"filename": "nnez-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "5212a577e2ea3c7327e5d50dfbcee0bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18051,
"upload_time": "2025-10-23T19:54:45",
"upload_time_iso_8601": "2025-10-23T19:54:45.692254Z",
"url": "https://files.pythonhosted.org/packages/87/56/52a8ca050241d17deda6f8c0dfb7705890d6bb4f92f520a7fc470c5e8809/nnez-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 19:54:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "nnez",
"github_not_found": true,
"lcname": "nnez"
}
JSON
