icalens 0.1.0__tar.gz

icalens-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/icalens
+    permissions:
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

icalens-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+demo/output/

icalens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sida Liu and Feijiang Han
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

icalens-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: icalens
+Version: 0.1.0
+Summary: Fit, share, and apply ICA lenses for language-model activations.
+Project-URL: Homepage, https://liusida.github.io/ica-lens-paper/
+Project-URL: Repository, https://github.com/liusida/icalens
+Author: Sida Liu, Feijiang Han
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: ICA,activations,interpretability,language-models
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: huggingface-hub>=0.25
+Requires-Dist: numpy>=1.24
+Requires-Dist: safetensors>=0.4
+Requires-Dist: torch>=2.1
+Requires-Dist: tqdm>=4.66
+Description-Content-Type: text/markdown
+
+# ICA Lens
+
+ICA Lens fits, shares, and applies Independent Component Analysis bases for
+language-model activations. Version 0.1 operates on activations supplied by the
+caller; it does not load language models or capture activations.
+
+```bash
+uv add icalens
+```
+
+Load a published lens:
+
+```python
+from icalens import ICALens
+
+lens = ICALens.from_pretrained("liusida/icalens-gpt2-small")
+scores = lens.transform(activations, layer=6)
+reconstructed = lens.inverse_transform(scores, layer=6)
+```
+
+Fit and publish your own:
+
+```python
+from icalens import ICALens
+
+lens = ICALens(
+    base_model="openai-community/gpt2",
+    base_model_revision="FULL_COMMIT_HASH",
+    activation_site="resid_post",
+)
+lens.fit(activations, layer=6, random_state=0)
+lens.save("./my-icalens")
+lens.push_to_hub("username/icalens-gpt2-small")
+```
+
+Inputs may be NumPy arrays or PyTorch tensors. Leading dimensions are treated
+as sample dimensions and the final dimension must be the model hidden size.
+Fitting uses ICA Lens's built-in PyTorch FastICA implementation and can run on
+the input tensor's device. NumPy inputs are fitted on CPU. ICA Lens does not
+depend on scikit-learn or SciPy.
+
+See [`docs/api.md`](docs/api.md) and
+[`docs/artifact-format.md`](docs/artifact-format.md) for the initial API and
+portable artifact format.
+
+For the 1,000-token GPT-2/Pile-10k fitting demo, run:
+
+```bash
+uv sync
+uv run python demo/fit.py
+```

icalens-0.1.0/README.md

@@ -0,0 +1,51 @@
+# ICA Lens
+
+ICA Lens fits, shares, and applies Independent Component Analysis bases for
+language-model activations. Version 0.1 operates on activations supplied by the
+caller; it does not load language models or capture activations.
+
+```bash
+uv add icalens
+```
+
+Load a published lens:
+
+```python
+from icalens import ICALens
+
+lens = ICALens.from_pretrained("liusida/icalens-gpt2-small")
+scores = lens.transform(activations, layer=6)
+reconstructed = lens.inverse_transform(scores, layer=6)
+```
+
+Fit and publish your own:
+
+```python
+from icalens import ICALens
+
+lens = ICALens(
+    base_model="openai-community/gpt2",
+    base_model_revision="FULL_COMMIT_HASH",
+    activation_site="resid_post",
+)
+lens.fit(activations, layer=6, random_state=0)
+lens.save("./my-icalens")
+lens.push_to_hub("username/icalens-gpt2-small")
+```
+
+Inputs may be NumPy arrays or PyTorch tensors. Leading dimensions are treated
+as sample dimensions and the final dimension must be the model hidden size.
+Fitting uses ICA Lens's built-in PyTorch FastICA implementation and can run on
+the input tensor's device. NumPy inputs are fitted on CPU. ICA Lens does not
+depend on scikit-learn or SciPy.
+
+See [`docs/api.md`](docs/api.md) and
+[`docs/artifact-format.md`](docs/artifact-format.md) for the initial API and
+portable artifact format.
+
+For the 1,000-token GPT-2/Pile-10k fitting demo, run:
+
+```bash
+uv sync
+uv run python demo/fit.py
+```

icalens-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third-party notices
+
+The internal FastICA implementation in `src/icalens/_fastica.py` is adapted
+from [FastICA_torch](https://github.com/liusida/FastICA_torch), copyright 2024
+Richard Hakim, under the MIT License:
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

icalens-0.1.0/demo/README.md

@@ -0,0 +1,95 @@
+# ICA Lens fitting demo
+
+Install the development dependencies and fit a lens from 1,000 Pile-10k tokens:
+
+```bash
+uv sync
+uv run python demo/fit.py
+```
+
+By default, the demo:
+
+1. Streams text from `NeelNanda/pile-10k`.
+2. Builds a 1,000-token candidate pool from independently tokenized documents.
+3. Uses all 1,000 positions for fitting by default.
+4. Preserves each sampled token's original left context during activation capture.
+5. Loads `openai-community/gpt2` on CUDA through `gb10-load-llm`.
+6. Captures `outputs.hidden_states[7]`, recorded as ICA Lens layer 6 after
+   excluding the initial embedding state.
+7. Fits a full 768-component ICA Lens.
+8. Saves it under `demo/output/icalens-gpt2-small-1k`.
+
+By default, `--candidate-tokens` equals `--token-budget`. Set it explicitly to
+sample the fitting tokens from a larger pool:
+
+```bash
+uv run python demo/fit.py \
+  --candidate-tokens 10000 \
+  --token-budget 1000 \
+  --max-iter 1000 \
+  --seed 0
+```
+
+`--max-iter` controls the fixed number of FastICA fixed-point iterations.
+The fitting demo displays a tqdm bar with the current convergence limit and
+mean contrast objective (`obj`). ICA Lens deliberately runs exactly
+`--max-iter` iterations: the classical FastICA tolerance criterion is treated
+as diagnostic-only because it is not an appropriate stopping rule in the LLM
+activation regime. The displayed objective uses the selected FastICA contrast:
+`log(cosh(x))`, `-exp(-x²/2)`, or `x⁴/4`.
+
+The demo also displays token-rate progress bars while building the Pile-10k
+candidate pool and capturing the sampled GPT-2 activations.
+
+To test whether a fit stays within an ordinary 16 GiB GPU budget, cap the
+PyTorch CUDA allocator:
+
+```bash
+uv run python demo/fit.py \
+  --layers 6 \
+  --token-budget 1000000 \
+  --fit-batch-size 8192 \
+  --max-vram-gb 16
+```
+
+The script reports peak PyTorch CUDA memory at the end. This cap covers
+allocations managed by PyTorch, but not CUDA context memory or allocations made
+directly by non-PyTorch libraries, so it is a close OOM test rather than a full
+hardware emulator.
+
+Selected activations are retained in CPU memory. Whitening statistics,
+FastICA updates, and final source scaling are computed in repeated CUDA batches,
+so GPU memory scales with `--fit-batch-size` rather than the total token count.
+
+Fit several layers with a comma-separated list:
+
+```bash
+uv run python demo/fit.py --layers 0,6,11
+```
+
+Use `--layers all` to fit all 12 GPT-2 transformer blocks. The default single
+layer is intended as a quick end-to-end check; a full published artifact should
+use a larger, explicitly sampled token corpus.
+
+The demo requires network access for Hugging Face downloads and a CUDA device.
+
+## Apply the saved lens
+
+After fitting layer 6, apply it to fresh text:
+
+```bash
+uv run python demo/apply.py
+```
+
+The script loads the local artifact, captures GPT-2 activations from the exact
+base-model revision recorded in its manifest, and prints the largest signed ICA
+component scores at each token.
+
+Use custom text or another saved artifact with:
+
+```bash
+uv run python demo/apply.py \
+  --lens demo/output/icalens-gpt2-small-1k \
+  --layer 6 \
+  --text "The boat reached the bank before sunset."
+```

icalens-0.1.0/demo/apply.py

@@ -0,0 +1,92 @@
+"""Apply a saved ICA Lens to fresh GPT-2 text."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import torch
+from gb10_load_llm import load_model_to_cuda
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+from icalens import ICALens
+
+DEFAULT_LENS = Path(__file__).parent / "output" / "icalens-gpt2-small"
+DEFAULT_TEXT = "She deposited the check at the bank before walking along the river bank."
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--lens", type=Path, default=DEFAULT_LENS)
+    parser.add_argument("--text", default=DEFAULT_TEXT)
+    parser.add_argument("--layer", type=int, default=6)
+    parser.add_argument("--top-k", type=int, default=5)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    if not torch.cuda.is_available():
+        raise RuntimeError("This GB10 demo requires a CUDA device.")
+    if args.top_k <= 0:
+        raise ValueError("--top-k must be positive")
+
+    lens = ICALens.from_pretrained(args.lens)
+    if args.layer not in lens.available_layers:
+        raise ValueError(
+            f"layer {args.layer} is not in this lens; available layers: {lens.available_layers}"
+        )
+
+    tokenizer = AutoTokenizer.from_pretrained(
+        lens.base_model,
+        revision=lens.base_model_revision,
+    )
+    model = load_model_to_cuda(
+        AutoModelForCausalLM,
+        lens.base_model,
+        revision=lens.base_model_revision,
+        device="cuda",
+        dtype=torch.bfloat16,
+        touch="auto",
+        low_cpu_mem_usage=True,
+    )
+    model.eval()
+
+    encoded = tokenizer(
+        args.text,
+        return_tensors="pt",
+        truncation=True,
+        max_length=tokenizer.model_max_length,
+    )
+    input_ids = encoded["input_ids"].to("cuda")
+    attention_mask = encoded["attention_mask"].to("cuda")
+    with torch.inference_mode():
+        outputs = model(
+            input_ids=input_ids,
+            attention_mask=attention_mask,
+            output_hidden_states=True,
+            use_cache=False,
+        )
+    if outputs.hidden_states is None:
+        raise RuntimeError("GPT-2 did not return hidden states.")
+
+    activations = outputs.hidden_states[args.layer + 1][0].to(dtype=torch.float32)
+    scores = lens.transform(activations, layer=args.layer)
+    top_k = min(args.top_k, scores.shape[-1])
+    top_indices = torch.topk(scores.abs(), k=top_k, dim=-1).indices
+    tokens = tokenizer.convert_ids_to_tokens(input_ids[0])
+
+    print(f"Lens: {args.lens}")
+    print(f"Base model: {lens.base_model}@{lens.base_model_revision}")
+    print(f"Layer: {args.layer}")
+    print()
+    for position, token in enumerate(tokens):
+        entries = [
+            f"C{component.item()}={scores[position, component].item():+.3f}"
+            for component in top_indices[position]
+        ]
+        print(f"{position:>3} {token!r:<18} {'  '.join(entries)}")
+
+
+if __name__ == "__main__":
+    main()