Add CircuitLens feature-circuit attribution

[Xmaster6y]

Summary

• add model-agnostic CircuitLens artifacts and tensor decompositions for upstream transcoder features, frozen-pattern attention head/source-token contributions, and downstream output logits
• run attribution through public Target and HookSession activation/gradient capture APIs, including graph-retaining activation capture
• preserve existing gradients on model parameters and caller-owned leaf inputs, including their original .grad object identity
• fail closed when a configured hook site is reached more than once, preventing ambiguous forward/backward pairing for reused modules
• validate aligned attention-head selections and non-negative, in-range artifact positions and logit indices
• make local-Jacobian, frozen-attention, and frozen-nonlinearity conventions explicit and serialize them with contributor scores
• keep transformer-lens and circuit-tracer in an optional circuit-lens integration extra rather than TDHook core dependencies
• add analytical and contract-focused coverage for all attribution paths and failure modes

Validation

• uv run pre-commit run --all-files
• uv run pytest tests -q (682 passed, 1 skipped)
• uv run pytest tests/attribution/test_circuit_lens.py tests/test_session.py --cov=src --cov-report=term-missing -q (CircuitLens: 100% line coverage)
• uv build

Closes #125

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-31T20:27:29.795513Z	7fa3842	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.45%. Comparing base (c403cd2) to head (ac4141e).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #131      +/-   ##
==========================================
+ Coverage   98.36%   98.45%   +0.09%     
==========================================
  Files          53       54       +1     
  Lines        4091     4336     +245     
==========================================
+ Hits         4024     4269     +245     
  Misses         67       67              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[cubic-dev-ai]

All reported issues were addressed across 6 files

_{You’re at about 99% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7fa3842d8d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".