ICA Lens

ICA Lens fits, shares, and applies Independent Component Analysis bases for language-model activations. The core API operates on activations supplied by the caller; it does not load language models or capture activations.

uv add icalens

Load a published lens:

from icalens import ICALens

lens = ICALens.from_pretrained("sida/icalens-gpt2-small-pile10k")
scores = lens.transform(activations, layer=6)
reconstructed = lens.inverse_transform(scores, layer=6)
energy = lens.energy(scores)  # per-token component fractions summing to 1

Fit and publish your own:

from icalens import ICALens

lens = ICALens(
    model_id="openai-community/gpt2",
    model_type="base",
    activation_site="resid_post",
)
lens.fit(activations, layer=6, random_state=0)
lens.save("./my-icalens")
lens.push_to_hub("username/icalens-gpt2-small")

For the standalone publishing demo, create a project-root .env file containing a Hugging Face token with write permission:

HF_TOKEN=hf_...

The .env file is ignored by Git. Publish a saved lens with:

uv run python demo/publish.py \
  --lens ./my-icalens \
  username/icalens-model-name

Instruction-tuned checkpoints use the same activation-level API and are identified explicitly in their portable metadata:

lens = ICALens(
    model_id="Qwen/Qwen2.5-0.5B-Instruct",
    model_type="instruct",
)

model_type describes the checkpoint and accepts "base" or "instruct". The standard icalens installation can capture and analyze text or completed chat conversations directly. result = lens.analyze(text, layer=6) returns aligned tokens, activations, signed scores, and per-token component energy shares.

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 and docs/artifact-format.md for the public API and portable artifact format.

For the 1,000-token GPT-2/Pile-10k fitting demo, run:

uv sync
uv run python demo/fit.py

For the corresponding instruct-model demo using assistant tokens from UltraChat conversations, run:

uv run python demo/fit_chat.py --layers 12

Then inspect assistant-token component scores with:

uv run python demo/apply_chat.py

Both apply.py and apply_chat.py also write standalone interactive HTML explorers under demo/output/; pass --output-file to choose another path.

Project links

Data verified by PyPI on Aug 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.6)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for liusida from gravatar.com liusida

Credits

Author: Sida Liu, Feijiang Han

GitHub Statistics

Data verified by PyPI on Aug 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Tags

ICA activations interpretability language-models

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

icalens-0.2.1.tar.gz (300.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

icalens-0.2.1-py3-none-any.whl (22.7 kB view details)

Uploaded Python 3

File details

Details for the file icalens-0.2.1.tar.gz.

File metadata

  • Download URL: icalens-0.2.1.tar.gz
  • Upload date:
  • Size: 300.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for icalens-0.2.1.tar.gz
Algorithm Hash digest
SHA256 b056d1fb3743cd5ec35863b5bcae348af416b6adb6cf6787cc48f6af7378871e
MD5 043ee567d54f7012f6b2337ae7495956
BLAKE2b-256 8b0d177a4a1bee118bef72080cb3a24a16d746c81f8714815902edc764d944c9

See more details on using hashes here.

Provenance

The following attestation bundles were made for icalens-0.2.1.tar.gz:

Publisher: release.yml on liusida/icalens

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file icalens-0.2.1-py3-none-any.whl.

File metadata

  • Download URL: icalens-0.2.1-py3-none-any.whl
  • Upload date:
  • Size: 22.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for icalens-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f353b5982214372fbbcf602f1935fbb03235416f83c10cb5724003d76d34a908
MD5 6af3f12cfbcf2e772577f4d204ff6159
BLAKE2b-256 827de146e0657f72e77ec5ab80835d7e776875ecf32d65ae2ff070a309984925

See more details on using hashes here.

Provenance

The following attestation bundles were made for icalens-0.2.1-py3-none-any.whl:

Publisher: release.yml on liusida/icalens

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

Pre-release

0.3.0.dev1

2 files

0.2.2

2 files

This release

0.2.1 This release

2 files

0.2.0

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page