icalens 0.2.2__tar.gz → 0.3.0.dev1__tar.gz

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

@@ -11,6 +11,8 @@ __pycache__/
 .ruff_cache/
 .coverage
 htmlcov/
+site/
 demo/output/
 experiments/output/
-experiments/
+experiments/
+.worktrees/

icalens-0.3.0.dev1/.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+mkdocs:
+  configuration: mkdocs.yml

{icalens-0.2.2 → icalens-0.3.0.dev1}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: icalens
-Version: 0.2.2
+Version: 0.3.0.dev1
 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
@@ -43,6 +44,7 @@ result = lens.analyze("She deposited the check at the bank.", layer=6)
 
 print(result.tokens)
 print(result.scores)
+result.to_html("analysis.html")
 ```
 
 Fit and publish your own:
@@ -89,6 +91,8 @@ lens = ICALens(
 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.
+`result.to_html("analysis.html")` writes a self-contained interactive explorer;
+pass `metric="energy"` to visualize component energy shares instead of scores.
 
 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.
@@ -96,9 +100,8 @@ 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 public API and
-portable artifact format.
+See the [documentation](https://icalens.readthedocs.io/) for the complete text,
+conversation, fitting, publishing, and HTML-export workflows.
 
 For the 1,000-token GPT-2/Pile-10k fitting demo, run:
 
@@ -107,8 +110,8 @@ uv sync
 uv run python demo/fit.py
 ```
 
-For the corresponding instruct-model demo using assistant tokens from
-UltraChat conversations, run:
+For the corresponding instruct-model demo using all formatted UltraChat
+conversation tokens, including template markers, run:
 
 ```bash
 uv run python demo/fit_chat.py --layers 12
@@ -122,3 +125,29 @@ 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.
+
+## Installed-package smoke test
+
+After installing a wheel or PyPI release in a clean project, run the bundled
+end-to-end check:
+
+```bash
+uv run icalens-smoke-test
+```
+
+By default, the suite checks both public input paths: raw text through the
+published GPT-2 lens and a formatted conversation through the published
+Qwen3.5-2B instruct lens. Each case lazily downloads one ICA layer, verifies
+finite scores and normalized energy, checks reconstruction shape, and writes
+`icalens-smoke-text.html` or `icalens-smoke-chat.html`.
+
+Run only one path when iterating locally:
+
+```bash
+uv run icalens-smoke-test text
+uv run icalens-smoke-test chat
+```
+
+Use `--text-lens`, `--text-layer`, `--text-input`, `--chat-lens`,
+`--chat-layer`, `--chat-input`, `--chat-response`, `--device`, and
+`--output-dir` to override the defaults.

{icalens-0.2.2 → icalens-0.3.0.dev1}/README.md

@@ -18,6 +18,7 @@ result = lens.analyze("She deposited the check at the bank.", layer=6)
 
 print(result.tokens)
 print(result.scores)
+result.to_html("analysis.html")
 ```
 
 Fit and publish your own:
@@ -64,6 +65,8 @@ lens = ICALens(
 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.
+`result.to_html("analysis.html")` writes a self-contained interactive explorer;
+pass `metric="energy"` to visualize component energy shares instead of scores.
 
 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.
@@ -71,9 +74,8 @@ 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 public API and
-portable artifact format.
+See the [documentation](https://icalens.readthedocs.io/) for the complete text,
+conversation, fitting, publishing, and HTML-export workflows.
 
 For the 1,000-token GPT-2/Pile-10k fitting demo, run:
 
@@ -82,8 +84,8 @@ uv sync
 uv run python demo/fit.py
 ```
 
-For the corresponding instruct-model demo using assistant tokens from
-UltraChat conversations, run:
+For the corresponding instruct-model demo using all formatted UltraChat
+conversation tokens, including template markers, run:
 
 ```bash
 uv run python demo/fit_chat.py --layers 12
@@ -97,3 +99,29 @@ 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.
+
+## Installed-package smoke test
+
+After installing a wheel or PyPI release in a clean project, run the bundled
+end-to-end check:
+
+```bash
+uv run icalens-smoke-test
+```
+
+By default, the suite checks both public input paths: raw text through the
+published GPT-2 lens and a formatted conversation through the published
+Qwen3.5-2B instruct lens. Each case lazily downloads one ICA layer, verifies
+finite scores and normalized energy, checks reconstruction shape, and writes
+`icalens-smoke-text.html` or `icalens-smoke-chat.html`.
+
+Run only one path when iterating locally:
+
+```bash
+uv run icalens-smoke-test text
+uv run icalens-smoke-test chat
+```
+
+Use `--text-lens`, `--text-layer`, `--text-input`, `--chat-lens`,
+`--chat-layer`, `--chat-input`, `--chat-response`, `--device`, and
+`--output-dir` to override the defaults.

{icalens-0.2.2 → icalens-0.3.0.dev1}/demo/README.md

@@ -38,6 +38,32 @@ 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`.
 
+For parallel FastICA, every saved layer also records an objective curve in
+`icalens.json` under `layers.<layer>.fitting.objective_history`. At each
+recorded iteration, the contrast is averaged over fitting tokens for each
+component, then summarized across components at the minimum, 10th, 20th, ...,
+90th percentile, and maximum. Its `iterations`, `percentiles`, and `values`
+arrays can be plotted directly as percentile curves or nested colored bands.
+Use `--objective-every N` to record every Nth iteration; the final iteration is
+always included. The default is `1`.
+
+After the fixed-point iterations, ICA Lens makes one final blockwise objective
+pass and renumbers components by descending absolute contrast deviation from
+the standard-Gaussian baseline. `C0` is therefore the strongest non-Gaussian
+component within that layer. The manifest retains every component's raw
+objective and baseline-relative strength.
+
+Plot the first four available layers from a local, progressively written lens:
+
+```bash
+uv run python demo/plot_objective.py \
+  demo/output/icalens-qwen3.5-2b-ultrachat-10m
+```
+
+Use `--layers 0,1,2`, `--first 6`, or `--output path/to/curves.png` to customize
+the selection and output. Nested colored bands show min–max, p10–p90, ...,
+p40–p60, with the median drawn as a line.
+
 The demo also displays token-rate progress bars while building the Pile-10k
 candidate pool and capturing the sampled GPT-2 activations.
 
@@ -92,9 +118,16 @@ uv run python demo/fit.py \
 
 This captures layers 0–1, fits them, releases their activations, and then
 repeats for layers 2–3. Smaller groups use less memory but require more complete
-passes over the tokenized dataset. The default `0` captures all requested
+passes over the tokenized dataset. Each capture pass stops immediately after
+its highest requested transformer block, so an early-layer group does not run
+the unused remainder of the model. The default `0` captures all requested
 layers in one pass.
 
+After each layer finishes fitting, the demos atomically checkpoint the growing
+lens to `--output`, including that layer's objective history. If a later layer
+fails or the run is interrupted, every previously completed layer remains
+loadable from the output directory.
+
 The demo requires network access for Hugging Face downloads and a CUDA device.
 
 Use every token available under the demo's per-document context limit without
@@ -112,19 +145,34 @@ reserved memory at the end.
 
 ## Fit an instruct-model lens from conversations
 
-Fit a Qwen2.5-0.5B-Instruct lens on assistant-content tokens from streamed
+Fit a Qwen2.5-0.5B-Instruct lens on all formatted tokens from streamed
 UltraChat 200k conversations:
 
 ```bash
 uv run python demo/fit_chat.py --layers 12
 ```
 
+Qwen3.5 multimodal checkpoints can be fitted as text-only language models. The
+loader selects the language backbone, while chat templating and assistant-token
+selection use the same interface:
+
+```bash
+uv run python demo/fit_chat.py \
+  --model Qwen/Qwen3.5-2B \
+  --layers 12 \
+  --token-budget 100000 \
+  --max-iter 20 \
+  --output demo/output/icalens-qwen3.5-2b-ultrachat-100k
+```
+
+Qwen3.5-2B has 24 language layers indexed from 0 through 23 and hidden size
+2048. Use at least 2049 fitting tokens for a full-component lens.
+
 The script uses the tokenizer's chat template and offset mapping to distinguish
 message content from role markers and other template control tokens. The
-default `--token-scope assistant` therefore fits only assistant-content token
-activations while retaining the complete preceding conversation as context.
-Other supported scopes are `user`, `content` (all message content), and `all`
-(including template tokens).
+default `--token-scope all` fits every formatted position, including template
+tokens. Other supported scopes are `assistant`, `user`, and `content` (all
+message content but no template markers).
 
 As in the plain-text demo, `--candidate-tokens` defaults to `--token-budget`.
 For a larger deterministic candidate pool, run:
@@ -152,18 +200,18 @@ uv run python demo/fit_chat.py \
 ```
 
 Ask the model to generate a response and apply the resulting instruct lens to
-the generated assistant tokens:
+the complete formatted conversation:
 
 ```bash
 uv run python demo/apply_chat.py
 ```
 
 The script first generates a response, then performs a full forward pass over
-the completed conversation so each generated token has an activation aligned
+the completed conversation so each formatted token has an activation aligned
 with the same chat formatting used during fitting. The default output shows
-component scores only for generated assistant-content tokens. Pass `--user`
-and optionally `--system` to supply a different prompt. `--token-scope` accepts
-the same `assistant`, `user`, `content`, and `all` choices as the fitting demo:
+component scores for all formatted tokens. Pass `--user` and optionally
+`--system` to supply a different prompt. `--token-scope` accepts the same
+`assistant`, `user`, `content`, and `all` choices as the fitting demo:
 
 ```bash
 uv run python demo/apply_chat.py \
@@ -178,6 +226,25 @@ The command also writes a self-contained v5-style explorer to
 different location. The report works directly from disk and does not require
 the v5 server.
 
+For a predetermined multi-turn conversation, pass a quoted JSON list. The
+model generates an assistant response after each entry; the next user entry is
+then appended regardless of what the model said:
+
+```bash
+uv run python demo/apply_chat.py \
+  --user '["Hi, how are you?", "Nothing."]' \
+  --layer 7
+```
+
+Repeating the flag is equivalent and is often easier to type:
+
+```bash
+uv run python demo/apply_chat.py \
+  --user "Hi, how are you?" \
+  --user "Nothing." \
+  --layer 7
+```
+
 ## Apply the saved lens
 
 After fitting layer 6, apply it to fresh text:
@@ -204,6 +271,11 @@ includes responsive token cards, signed component bars, component highlighting,
 card-width control, and an opacity cutoff. Override the path with
 `--output-file PATH`.
 
+Pass `--metric score` (the default) for signed ICA coordinates or
+`--metric energy` for nonnegative per-token squared-score fractions displayed
+as percentages. The selected metric controls ranking, terminal output, and the
+HTML explorer for both `apply.py` and `apply_chat.py`.
+
 ## Publish and verify a chat lens
 
 The fitting demo records exact dataset and sampling provenance. Upload through

{icalens-0.2.2 → icalens-0.3.0.dev1}/demo/apply.py

@@ -7,7 +7,6 @@ from pathlib import Path
 
 import torch
 from gb10_load_llm import load_model_to_cuda
-from html_explorer import write_explorer_html
 from transformers import AutoModelForCausalLM, AutoTokenizer
 
 from icalens import ICALens
@@ -23,10 +22,20 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--text", default=DEFAULT_TEXT)
     parser.add_argument("--layer", type=int, default=6)
     parser.add_argument("--top-k", type=int, default=5)
+    parser.add_argument(
+        "--metric",
+        choices=("score", "energy"),
+        default="score",
+        help="Rank and display signed ICA scores or per-token energy shares.",
+    )
     parser.add_argument("--output-file", type=Path, default=DEFAULT_OUTPUT_FILE)
     return parser.parse_args()
 
 
+def format_value(value: float, metric: str) -> str:
+    return f"{value:+.3f}" if metric == "score" else f"{value:.2%}"
+
+
 def main() -> None:
     args = parse_args()
     if not torch.cuda.is_available():
@@ -62,46 +71,29 @@ def main() -> None:
         tokenizer=tokenizer,
         context_length=tokenizer.model_max_length,
     )
-    scores = result.scores
-    top_k = min(args.top_k, scores.shape[-1])
-    top_indices = torch.topk(scores.abs(), k=top_k, dim=-1).indices
-    token_ids = result.token_ids.tolist()
+    values = result.scores if args.metric == "score" else result.energy
+    ranking_values = values.abs() if args.metric == "score" else values
+    top_k = min(args.top_k, values.shape[-1])
+    top_indices = torch.topk(ranking_values, k=top_k, dim=-1).indices
     tokens = result.tokens
 
     print(f"Lens: {args.lens}")
     print(f"Model: {lens.model_id}@{lens.model_revision} ({lens.model_type})")
     print(f"Layer: {args.layer}")
+    print(f"Metric: {args.metric}")
     print()
     for position, token in enumerate(tokens):
         entries = [
-            f"C{component.item()}={scores[position, component].item():+.3f}"
+            f"C{component.item()}={format_value(values[position, component].item(), args.metric)}"
             for component in top_indices[position]
         ]
         print(f"{position:>3} {token!r:<18} {'  '.join(entries)}")
 
-    html_tokens = [
-        {
-            "position": position,
-            "token": token,
-            "token_text": tokenizer.decode([token_ids[position]]),
-            "top": [
-                {
-                    "component": int(component),
-                    "score": float(scores[position, component]),
-                }
-                for component in top_indices[position]
-            ],
-        }
-        for position, token in enumerate(tokens)
-    ]
-    output_file = write_explorer_html(
+    output_file = result.to_html(
         args.output_file,
         title="ICA Lens Text Explorer",
-        model=f"{lens.model_id}@{lens.model_revision}",
-        layer=args.layer,
-        input_text=args.text,
-        token_scope="all text tokens",
-        tokens=html_tokens,
+        metric=args.metric,
+        top_k=args.top_k,
     )
     print()
     print(f"HTML explorer: {output_file}")