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". Install icalens[analyze] to 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

Provides Extra

analyze

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.0.tar.gz (301.0 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.0-py3-none-any.whl (22.7 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: icalens-0.2.0.tar.gz
  • Upload date:
  • Size: 301.0 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.0.tar.gz
Algorithm Hash digest
SHA256 d5a1af178033c7bb65d74f5aa992581aec1a786b981b2aea33198daccabd3366
MD5 2d78c389dab748c68bd10816293a9c5a
BLAKE2b-256 d657c4a5ca816f57b5dfc41610a2cb7ae144e930160a60d63db9b2e47c64a4df

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: icalens-0.2.0-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.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9f11aec032fe5efc17e982dccae444ffbdfd48b5ab9fa61465cd99bfef3dd00a
MD5 6e0e9b6eee114333dcceb6e470dad540
BLAKE2b-256 3d0ddfbf8b37d35748651ae547c90dff89e417d52b07b8fe2ecf37894d8ddfb1

See more details on using hashes here.

Provenance

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

0.2.1

2 files

This release

0.2.0 This release

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