ICA Lens

ICA Lens fits, shares, and applies Independent Component Analysis bases for language-model activations. It can capture activations directly from text or operate on activation tensors supplied by the caller.

uv add icalens

Load a published lens:

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)

print(result.tokens)
print(result.scores)

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.2.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.2-py3-none-any.whl (22.7 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: icalens-0.2.2.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.2.tar.gz
Algorithm Hash digest
SHA256 3b99bea16a5a709a0d4c25254ab695e25e8d58a86a1951c8248cd76a2e2aa05e
MD5 f2e9cd3c9acafe1ac4f3ac0d479e93d0
BLAKE2b-256 e45a36ec5f8b2f4eb0530c6880c9a21c611763e4b4c7bc1d5dcd10a8ddcde3a3

See more details on using hashes here.

Provenance

The following attestation bundles were made for icalens-0.2.2.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.2-py3-none-any.whl.

File metadata

  • Download URL: icalens-0.2.2-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.2-py3-none-any.whl
Algorithm Hash digest
SHA256 dcba4ba84451c486a1d558654e0e2bbcf2f0cc351b9d094b4fa3319ad0c85fd6
MD5 1ad918ffb17a9907eabe8d67277e2510
BLAKE2b-256 58e762ec1d4204c451e3fcdad02ae68fbbf61f6542d7e9be01c9b6d6609ad1fb

See more details on using hashes here.

Provenance

The following attestation bundles were made for icalens-0.2.2-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

This release

0.2.2 This release

2 files

0.2.1

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