icalens 0.3.0.dev1__tar.gz → 0.3.2__tar.gz

{icalens-0.3.0.dev1 → icalens-0.3.2}/.gitignore

@@ -12,7 +12,12 @@ __pycache__/
 .coverage
 htmlcov/
 site/
+site-zh/
 demo/output/
 experiments/output/
 experiments/
 .worktrees/
+
+.ipynb_checkpoints/
+icalens-output/
+three-icalens-fit/

icalens-0.3.2/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: icalens
+Version: 0.3.2
+Summary: Fit, share, and apply ICA lenses for language-model activations.
+Project-URL: Homepage, https://liusida.github.io/ica-lens-paper/
+Project-URL: Documentation, https://icalens.readthedocs.io/
+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: datasets>=4.0
+Requires-Dist: gb10-load-llm>=0.1.2
+Requires-Dist: huggingface-hub>=0.25
+Requires-Dist: numpy>=1.24
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: safetensors>=0.4
+Requires-Dist: torch>=2.1
+Requires-Dist: tqdm>=4.66
+Requires-Dist: transformers>=5.0
+Description-Content-Type: text/markdown
+
+# ICA Lens
+
+ICA Lens interprets language-model activations with Independent Component
+Analysis. It is substantially more compute-efficient to fit than an SAE
+dictionary and supports base and instruction-tuned language models.
+
+**[Documentation](https://icalens.readthedocs.io/en/latest/)** ·
+**[中文文档](https://icalens.readthedocs.io/zh_CN/latest/)** ·
+**[Paper](https://arxiv.org/abs/2606.11722)** ·
+**[Model collection](https://huggingface.co/sida)**
+
+## Get started
+
+```bash
+pip install icalens
+```
+
+Load a published Lens and analyze text:
+
+```python
+from icalens import ICALens
+
+lens = ICALens.from_pretrained("sida/icalens-gpt2-small-pile10k")
+result = lens.analyze("She deposited the check at the bank.", layer=6)
+result
+```
+
+In Jupyter or Colab, the final `result` expression displays an interactive
+token-level analysis:
+
+![ICA Lens token-level analysis in Jupyter](https://raw.githubusercontent.com/liusida/icalens/main/docs/assets/text-analysis-notebook.png)
+
+Use signed ICA scores or switch the explorer to per-token component energy.
+Save the same view as a standalone HTML file with:
+
+```python
+result.to_html("analysis.html")
+```
+
+The first analysis loads the language model and requested Lens layer. Later
+calls on the same `lens` reuse the model in memory. `device="auto"` uses CUDA
+when available and otherwise uses the CPU.
+
+## Analyze conversations
+
+Instruction-tuned models accept completed conversations using the standard
+`{role, content}` format:
+
+```python
+lens = ICALens.from_pretrained("sida/icalens-qwen3.5-2b-ultrachat-1m")
+result = lens.analyze(
+    [
+        {"role": "user", "content": "What is the most interesting science?"},
+        {"role": "assistant", "content": "Physics."},
+    ],
+    layer=16,
+)
+result
+```
+
+Chat templates are applied automatically, and template tokens and message
+turns are grouped in the interactive result.
+
+## Steering
+
+Generate normally or clamp a signed ICA coordinate during generation:
+
+```python
+messages = [{
+    "role": "user",
+    "content": "If you had to pick one, what is the most interesting science? Be brief.",
+}]
+
+baseline = lens.generate(messages, max_new_tokens=16)
+steered = lens.generate(
+    messages,
+    layer=5,
+    clamp=(188, -20.0),
+    max_new_tokens=16,
+)
+```
+
+Component labels, signs, and suitable targets must be established empirically
+for the exact Lens and layer. See the
+**[steering tutorial](https://icalens.readthedocs.io/en/latest/steering/)** for
+the reproducible inspection and calibration workflow.
+
+## Fit a Lens
+
+Run a small GPT-2/Pile-10k example with the installed CLI:
+
+```bash
+icalens fit text \
+  --model openai-community/gpt2 \
+  --dataset NeelNanda/pile-10k \
+  --layers 6 \
+  --token-budget 1000 \
+  --max-iter 20 \
+  --output icalens-output/gpt2-demo
+```
+
+Fit an instruction-tuned model from UltraChat conversations:
+
+```bash
+icalens fit chat \
+  --model Qwen/Qwen3.5-2B \
+  --dataset HuggingFaceH4/ultrachat_200k \
+  --layers 12 \
+  --token-budget 100000 \
+  --output icalens-output/qwen-demo
+```
+
+ICA Lens includes a PyTorch FastICA implementation and does not depend on
+SciPy or scikit-learn. Blockwise fitting and layer-at-a-time capture support
+larger token collections while bounding memory use.
+
+## Profile every fitted layer
+
+After fitting, profile the components against a representative corpus:
+
+```bash
+icalens profile \
+  --lens icalens-output/gpt2-demo \
+  --layers all \
+  --dataset NeelNanda/pile-10k \
+  --split train \
+  --max-tokens 10000
+```
+
+Profiles add sign statistics, high-energy examples, and logit-lens tokens to
+the existing Lens directory. They help label and inspect components without
+changing the fitted directions.
+
+## Publish to Hugging Face
+
+Authenticate with `hf auth login`, set `HF_TOKEN`, or add a `.env` file in the
+current directory containing a write-enabled token:
+
+```dotenv
+HF_TOKEN=hf_...
+```
+
+Then publish the saved Lens as a Hugging Face model repository:
+
+```bash
+icalens publish \
+  --lens icalens-output/gpt2-demo \
+  username/icalens-gpt2-demo
+```
+
+The artifact records the analyzed model, activation site, fitted layers,
+preprocessing, component profiles, and fitting and profiling provenance.
+Individual layer and profile files are downloaded lazily when a published Lens
+is used.
+
+## Learn more
+
+The documentation covers:
+
+- [Getting started](https://icalens.readthedocs.io/en/latest/getting-started/)
+- [Text and chat](https://icalens.readthedocs.io/en/latest/text-and-chat/)
+- [Component profiles](https://icalens.readthedocs.io/en/latest/component-profiles/)
+- [Scores and energy](https://icalens.readthedocs.io/en/latest/scores-and-energy/)
+- [Steering](https://icalens.readthedocs.io/en/latest/steering/)
+- [Reconstruction](https://icalens.readthedocs.io/en/latest/reconstruction/)
+- [Fitting and publishing](https://icalens.readthedocs.io/en/latest/fit-and-publish/)
+- [Python API](https://icalens.readthedocs.io/en/latest/api/)
+
+The repository also contains compact notebooks in [`demo/`](demo/) covering
+text analysis, conversations, reconstruction, fitting, and steering.
+
+## Authors
+
+- [Sida Liu](https://liusida.com/)
+- [Feijiang Han](https://feijianghan.com/)
+
+## Citation
+
+```bibtex
+@article{liu2026icalens,
+  title={ICA Lens: Interpreting Language Models Without Training Another Dictionary},
+  author={Liu, Sida and Han, Feijiang},
+  journal={arXiv preprint arXiv:2606.11722},
+  year={2026}
+}
+```

icalens-0.3.2/README.md

@@ -0,0 +1,186 @@
+# ICA Lens
+
+ICA Lens interprets language-model activations with Independent Component
+Analysis. It is substantially more compute-efficient to fit than an SAE
+dictionary and supports base and instruction-tuned language models.
+
+**[Documentation](https://icalens.readthedocs.io/en/latest/)** ·
+**[中文文档](https://icalens.readthedocs.io/zh_CN/latest/)** ·
+**[Paper](https://arxiv.org/abs/2606.11722)** ·
+**[Model collection](https://huggingface.co/sida)**
+
+## Get started
+
+```bash
+pip install icalens
+```
+
+Load a published Lens and analyze text:
+
+```python
+from icalens import ICALens
+
+lens = ICALens.from_pretrained("sida/icalens-gpt2-small-pile10k")
+result = lens.analyze("She deposited the check at the bank.", layer=6)
+result
+```
+
+In Jupyter or Colab, the final `result` expression displays an interactive
+token-level analysis:
+
+![ICA Lens token-level analysis in Jupyter](https://raw.githubusercontent.com/liusida/icalens/main/docs/assets/text-analysis-notebook.png)
+
+Use signed ICA scores or switch the explorer to per-token component energy.
+Save the same view as a standalone HTML file with:
+
+```python
+result.to_html("analysis.html")
+```
+
+The first analysis loads the language model and requested Lens layer. Later
+calls on the same `lens` reuse the model in memory. `device="auto"` uses CUDA
+when available and otherwise uses the CPU.
+
+## Analyze conversations
+
+Instruction-tuned models accept completed conversations using the standard
+`{role, content}` format:
+
+```python
+lens = ICALens.from_pretrained("sida/icalens-qwen3.5-2b-ultrachat-1m")
+result = lens.analyze(
+    [
+        {"role": "user", "content": "What is the most interesting science?"},
+        {"role": "assistant", "content": "Physics."},
+    ],
+    layer=16,
+)
+result
+```
+
+Chat templates are applied automatically, and template tokens and message
+turns are grouped in the interactive result.
+
+## Steering
+
+Generate normally or clamp a signed ICA coordinate during generation:
+
+```python
+messages = [{
+    "role": "user",
+    "content": "If you had to pick one, what is the most interesting science? Be brief.",
+}]
+
+baseline = lens.generate(messages, max_new_tokens=16)
+steered = lens.generate(
+    messages,
+    layer=5,
+    clamp=(188, -20.0),
+    max_new_tokens=16,
+)
+```
+
+Component labels, signs, and suitable targets must be established empirically
+for the exact Lens and layer. See the
+**[steering tutorial](https://icalens.readthedocs.io/en/latest/steering/)** for
+the reproducible inspection and calibration workflow.
+
+## Fit a Lens
+
+Run a small GPT-2/Pile-10k example with the installed CLI:
+
+```bash
+icalens fit text \
+  --model openai-community/gpt2 \
+  --dataset NeelNanda/pile-10k \
+  --layers 6 \
+  --token-budget 1000 \
+  --max-iter 20 \
+  --output icalens-output/gpt2-demo
+```
+
+Fit an instruction-tuned model from UltraChat conversations:
+
+```bash
+icalens fit chat \
+  --model Qwen/Qwen3.5-2B \
+  --dataset HuggingFaceH4/ultrachat_200k \
+  --layers 12 \
+  --token-budget 100000 \
+  --output icalens-output/qwen-demo
+```
+
+ICA Lens includes a PyTorch FastICA implementation and does not depend on
+SciPy or scikit-learn. Blockwise fitting and layer-at-a-time capture support
+larger token collections while bounding memory use.
+
+## Profile every fitted layer
+
+After fitting, profile the components against a representative corpus:
+
+```bash
+icalens profile \
+  --lens icalens-output/gpt2-demo \
+  --layers all \
+  --dataset NeelNanda/pile-10k \
+  --split train \
+  --max-tokens 10000
+```
+
+Profiles add sign statistics, high-energy examples, and logit-lens tokens to
+the existing Lens directory. They help label and inspect components without
+changing the fitted directions.
+
+## Publish to Hugging Face
+
+Authenticate with `hf auth login`, set `HF_TOKEN`, or add a `.env` file in the
+current directory containing a write-enabled token:
+
+```dotenv
+HF_TOKEN=hf_...
+```
+
+Then publish the saved Lens as a Hugging Face model repository:
+
+```bash
+icalens publish \
+  --lens icalens-output/gpt2-demo \
+  username/icalens-gpt2-demo
+```
+
+The artifact records the analyzed model, activation site, fitted layers,
+preprocessing, component profiles, and fitting and profiling provenance.
+Individual layer and profile files are downloaded lazily when a published Lens
+is used.
+
+## Learn more
+
+The documentation covers:
+
+- [Getting started](https://icalens.readthedocs.io/en/latest/getting-started/)
+- [Text and chat](https://icalens.readthedocs.io/en/latest/text-and-chat/)
+- [Component profiles](https://icalens.readthedocs.io/en/latest/component-profiles/)
+- [Scores and energy](https://icalens.readthedocs.io/en/latest/scores-and-energy/)
+- [Steering](https://icalens.readthedocs.io/en/latest/steering/)
+- [Reconstruction](https://icalens.readthedocs.io/en/latest/reconstruction/)
+- [Fitting and publishing](https://icalens.readthedocs.io/en/latest/fit-and-publish/)
+- [Python API](https://icalens.readthedocs.io/en/latest/api/)
+
+The repository also contains compact notebooks in [`demo/`](demo/) covering
+text analysis, conversations, reconstruction, fitting, and steering.
+
+## Authors
+
+- [Sida Liu](https://liusida.com/)
+- [Feijiang Han](https://feijianghan.com/)
+
+## Citation
+
+```bibtex
+@article{liu2026icalens,
+  title={ICA Lens: Interpreting Language Models Without Training Another Dictionary},
+  author={Liu, Sida and Han, Feijiang},
+  journal={arXiv preprint arXiv:2606.11722},
+  year={2026}
+}
+```

{icalens-0.3.0.dev1 → icalens-0.3.2}/demo/apply_chat.py

@@ -109,9 +109,7 @@ def main() -> None:
     if tokenizer.chat_template is None:
         raise RuntimeError(f"{lens.model_id} tokenizer does not define a chat template.")
 
-    user_turns = tuple(
-        turn for argument in (args.user or [(DEFAULT_USER,)]) for turn in argument
-    )
+    user_turns = tuple(turn for argument in (args.user or [(DEFAULT_USER,)]) for turn in argument)
     messages = []
     if args.system is not None:
         messages.append({"role": "system", "content": args.system})
@@ -247,9 +245,7 @@ def group_tokens_by_message(
     tokens: list[dict[str, object]],
 ) -> list[dict[str, object]]:
     """Group formatted token cards by the message that introduced them."""
-    rendered = tokenizer.apply_chat_template(
-        messages, tokenize=False, add_generation_prompt=False
-    )
+    rendered = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=False)
     encoded = tokenizer(
         rendered,
         add_special_tokens=False,
@@ -279,10 +275,7 @@ def group_tokens_by_message(
         opening_candidates = [
             index
             for index in range(content_token + 1)
-            if (
-                "start" in input_tokens[index].lower()
-                or "begin" in input_tokens[index].lower()
-            )
+            if ("start" in input_tokens[index].lower() or "begin" in input_tokens[index].lower())
             and (not message_starts or index > message_starts[-1])
         ]
         message_starts.append(opening_candidates[-1] if opening_candidates else content_token)
@@ -292,9 +285,7 @@ def group_tokens_by_message(
 
     role_counts = {"system": 0, "user": 0, "assistant": 0}
     groups = []
-    for message, start, end in zip(
-        visible_messages, message_starts, end_positions, strict=True
-    ):
+    for message, start, end in zip(visible_messages, message_starts, end_positions, strict=True):
         role = message["role"]
         role_counts[role] += 1
         title = role.title() if role == "system" else f"{role.title()} {role_counts[role]}"

icalens-0.3.2/demo/commands-2.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Refit the three base-model ICA lenses with model-aware document framing.
+# Each fit samples 1M rows from all usable Pile-10k tokens. New output paths
+# preserve the existing artifacts until these corrected lenses are validated.
+#
+# Gemma prerequisite: accept the license for google/gemma-2-2b on Hugging Face.
+
+echo "[1/6] Fitting GPT-2 Small"
+uv run icalens fit text \
+  --model openai-community/gpt2 \
+  --dataset NeelNanda/pile-10k \
+  --split train \
+  --text-field text \
+  --layers all \
+  --capture-layers-at-once 5 \
+  --candidate-tokens all \
+  --token-budget 1000000 \
+  --fit-batch-size 32768 \
+  --max-iter 50 \
+  --refresh-model-registry \
+  --output three-icalens-fit/icalens-gpt2-small-pile10k-1m
+
+echo "[2/6] Profiling GPT-2 Small"
+uv run icalens profile \
+  --lens three-icalens-fit/icalens-gpt2-small-pile10k-1m \
+  --layers all \
+  --dataset NeelNanda/pile-10k \
+  --split train \
+  --input-type text \
+  --text-field text \
+  --max-tokens 1000000 \
+  --top-k-examples 20 \
+  --min-energy 0.05
+
+echo "[3/6] Fitting Gemma 2 2B Base"
+uv run icalens fit text \
+  --model google/gemma-2-2b \
+  --dataset NeelNanda/pile-10k \
+  --split train \
+  --text-field text \
+  --layers all \
+  --capture-layers-at-once 5 \
+  --candidate-tokens all \
+  --token-budget 1000000 \
+  --fit-batch-size 32768 \
+  --max-iter 50 \
+  --refresh-model-registry \
+  --output three-icalens-fit/icalens-gemma-2-2b-pile10k-1m
+
+echo "[4/6] Profiling Gemma 2 2B Base"
+uv run icalens profile \
+  --lens three-icalens-fit/icalens-gemma-2-2b-pile10k-1m \
+  --layers all \
+  --dataset NeelNanda/pile-10k \
+  --split train \
+  --input-type text \
+  --text-field text \
+  --max-tokens 1000000 \
+  --top-k-examples 20 \
+  --min-energy 0.05
+
+echo "[5/6] Fitting Qwen3.5 2B Base"
+uv run icalens fit text \
+  --model Qwen/Qwen3.5-2B-Base \
+  --dataset NeelNanda/pile-10k \
+  --split train \
+  --text-field text \
+  --layers all \
+  --capture-layers-at-once 5 \
+  --candidate-tokens all \
+  --token-budget 1000000 \
+  --fit-batch-size 32768 \
+  --max-iter 50 \
+  --refresh-model-registry \
+  --output three-icalens-fit/icalens-qwen3.5-2b-base-pile10k-1m
+
+echo "[6/6] Profiling Qwen3.5 2B Base"
+uv run icalens profile \
+  --lens three-icalens-fit/icalens-qwen3.5-2b-base-pile10k-1m \
+  --layers all \
+  --dataset NeelNanda/pile-10k \
+  --split train \
+  --input-type text \
+  --text-field text \
+  --max-tokens 1000000 \
+  --top-k-examples 20 \
+  --min-energy 0.05
+
+echo "Finished fitting and profiling all three corrected base-model lenses."