neuronscope

NeuronScope

言語モデルに「なぜそう答えたのですか」と尋ねると、その原因となった実際のアテンションヘッドとニューロンをJSON形式で取得できます。コマンドラインから、またはMCP経由でエージェントから利用できます。

インストール

pip install neuronscope-cli

これでneuronscopeコマンドを利用できます。代わりにソースからインストールする場合（開発用、またはmainを追跡する場合）は、次のようにします。

git clone https://github.com/RudrenduPaul/NeuronScope
cd NeuronScope
pip install -e .

メモ

どのコマンドでも、初回実行時に要求されたモデルがHuggingFace Hubからダウンロードされます（gpt2は約500MB）。また、stderrに2行表示されますが、これは想定されたものであり、エラーではありません。CUDA GPUがない場合のCPUフォールバック通知と、未認証のHF Hubに関するレート制限通知です。どちらも問題が発生したことを意味しません。

クイックスタート

neuronscope trace gpt2 "The capital of France is Paris. The capital of Japan is" --top-k 5

このコマンドをそのまま実行した際の実際の出力です（stderrは、上記の想定される2つの警告だけになるよう省略しています）。

Prompt: The capital of France is Paris. The capital of Japan is
Predicted next token: ' Tokyo'
Top attention heads (by direct logit
            attribution)
┏━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Layer ┃ Head ┃ Logit attribution ┃
┡━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│     9 │    8 │            4.0679 │
│     8 │   11 │            2.9028 │
│    10 │    7 │           -1.4782 │
│     8 │   10 │           -1.3999 │
│    10 │    0 │            1.1424 │
└───────┴──────┴───────────────────┘
Top MLP neurons (by activation
          magnitude)
┏━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
┃ Layer ┃ Neuron ┃ Activation ┃
┡━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
│    10 │     97 │     7.8394 │
│    11 │    611 │     4.6954 │
│    11 │   2997 │     4.6468 │
│    10 │   1793 │     4.5443 │
│     9 │   1460 │     4.4196 │
└───────┴────────┴────────────┘

gpt2はTokyoを正しく予測し、ヘッドL9H8がその予測への最大の寄与要因です。同じ結果を機械可読形式で取得するには、--jsonを追加します。

neuronscope trace gpt2 "The capital of France is Paris. The capital of Japan is" --top-k 3 --json

{
  "schema_version": 1,
  "operation": "trace",
  "model": {
    "requested_name": "gpt2",
    "resolved_name": "gpt2",
    "backend": "transformer_lens",
    "device": "cpu",
    "n_layers": 12,
    "n_heads": 12,
    "d_model": 768,
    "d_mlp": 3072
  },
  "prompt": "The capital of France is Paris. The capital of Japan is",
  "predicted_token": " Tokyo",
  "predicted_token_id": 11790,
  "top_neurons": [
    { "layer": 10, "neuron_index": 97, "activation": 7.839381217956543 },
    { "layer": 11, "neuron_index": 611, "activation": 4.695372581481934 },
    { "layer": 11, "neuron_index": 2997, "activation": 4.646785736083984 }
  ],
  "top_heads": [
    { "layer": 9, "head_index": 8, "logit_attribution": 4.067923545837402 },
    { "layer": 8, "head_index": 11, "logit_attribution": 2.9028172492980957 },
    { "layer": 10, "head_index": 7, "logit_attribution": -1.4781968593597412 }
  ]
}

できること

NeuronScope は、TransformerLens を基盤とする CLI および MCP サーバーです。TransformerLens がモデルの読み込み、フック、活性値の計算を実際に行います。NeuronScope はその周りに安定した CLI、バージョン管理された JSON スキーマ、MCP サーバーを追加し、スクリプトやエージェントが TransformerLens のコードを直接書かなくても、「この出力を引き起こしたコンポーネントはどれか」と問い合わせられるようにします。

• trace：プロンプトをモデルに入力し、予測トークンへの直接的なロジット帰属度に基づいてアテンションヘッドを順位付けします。また、プロンプトの最後の位置における活性値の大きさに基づいて、MLP ニューロンを順位付けします。
• activations：各層の残差ストリーム、MLP ニューロンの活性値、アテンションパターンについて、形状、平均、標準偏差、最小値／最大値、活性値が最大となる系列位置を出力します。
• patch：指定した層の 1 つのコンポーネント（resid_pre、resid_mid、resid_post、attn_out、mlp_out、mlp_post のいずれか）をゼロアブレーションし、予測トークンとそのロジットがどのように変化したかを報告します。
• circuit：ベストエフォートの自動回路スケッチです。ロジット帰属度に基づいて候補となるヘッド／ニューロンを順位付けし、続いて、単一コンポーネントのアブレーションによってそれぞれの個別の因果効果を測定します。これは、クリーン／破損プロンプトのペアを使った完全なパスパッチングではなく、コンポーネント間の相互作用も捉えません。--json 出力の method フィールドには、その旨が明記されます。
• すべてのコマンドは、テーブルの代わりに schema_version が付与されたドキュメントを出力する --json に対応しています。また、同じ 4 つの操作を MCP ツールとしても利用でき、.model_dump() 経由で同一の形式を返します。そのため、同じ入力であれば、CLI の呼び出しと MCP ツールの呼び出しは同じドキュメントを生成します。
• 対応モデルは、transformer_lens.HookedTransformer.from_pretrained がサポートするモデルです。現時点で neuronscope-cli をインストールすると、TransformerLens 3.6.0 がインストールされます。TransformerLens 3.6.0 は 249 個の事前学習済みチェックポイントとエイリアス（OFFICIAL_MODEL_NAMES）に対応しており、GPT-2、Pythia、Llama、Gemma、Qwen などを利用できます。gpt2 のような小型モデルは、CPU でも快適に動作します。

NeuronScope は、TransformerLens、nnsight、SAELens、Anthropic の circuit-tracer、Neuronpedia に取って代わるものではありません。TransformerLens をラップし、単一のプロンプトに対するコンポーネントのトレースを高速かつスクリプト化可能にし、エージェントから呼び出せるようにするという、より限定的な用途を担います。より踏み込んだメカニズムの分析（SAE のトレーニング、トランスコーダーに基づく回路グラフ、ホストされた特徴の閲覧）は、これらのツールに任せています。

CLI リファレンス

すべてのコマンドは、位置引数として MODEL（HookedTransformer.from_pretrained が受け付ける任意の名前。例：gpt2 や EleutherAI/pythia-70m）と PROMPT を取ります。

コマンド	追加フラグ	説明
neuronscope trace MODEL PROMPT	--top-k INTEGER（デフォルト 10）、--json	予測される次のトークンについて、上位のアテンションヘッド（ロジット帰属度）と MLP ニューロン（活性化の大きさ）をランキングします
neuronscope activations MODEL PROMPT	--json	レイヤーごとの活性化の要約統計（残差ストリーム、MLP、アテンションパターン）を出力します
neuronscope patch MODEL PROMPT	--layer INTEGER（必須）、--component [resid_pre|resid_mid|resid_post|attn_out|mlp_out|mlp_post]（必須）、--json	1 つのコンポーネントをゼロアブレーションし、ロジット／予測の差分を報告します
neuronscope circuit MODEL PROMPT	--top-k INTEGER（デフォルト 10）、--json	単一コンポーネントのアブレーションをランキングし、ベストエフォートで回路の概要を作成します
neuronscope mcp-server	なし	stdio 経由で MCP サーバーを起動します

グローバルオプション：neuronscope --version、neuronscope <command> --help。終了コード：0 は成功、1 は実行時エラー（プロンプトがモデルのコンテキストウィンドウに対して長すぎる、--layer が範囲外など）、2 は Click の使用方法エラー（不正なフラグ）、3 は未対応のモデル名です。

MCP サーバー

NeuronScope には、AI エージェント（Claude、Cursor、または MCP 対応の任意のクライアント）が人間の手による CLI の実行なしに、直接トレース、検査、アブレーション、回路の概要作成を行える Model Context Protocol サーバーが付属しています。

追加機能をインストールします。

pip install "neuronscope-cli[mcp]"

MCP クライアントの設定に追加します（Claude Desktop の場合は claude_desktop_config.json）。

{
  "mcpServers": {
    "neuronscope": {
      "command": "uvx",
      "args": ["--from", "neuronscope-cli", "neuronscope-mcp"]
    }
  }
}

このサーバーは trace、activations、patch、circuit の 4 つのツールを公開します。各ツールは .model_dump() を介して、CLI の --json フラグが出力するものと同一の、pydantic モデル形式の JSON を返します。そのため、このサーバーを呼び出すエージェントと CLI を呼び出すスクリプトは、同じ入力に対して同じドキュメントを取得できます。実際の trace 呼び出しとその応答：

trace(model="gpt2", prompt="The capital of France is Paris. The capital of Japan is", top_k=3)

{
  "schema_version": 1,
  "operation": "trace",
  "predicted_token": " Tokyo",
  "predicted_token_id": 11790,
  "top_neurons": [
    { "layer": 10, "neuron_index": 97, "activation": 7.839381217956543 }
  ],
  "top_heads": [
    { "layer": 9, "head_index": 8, "logit_attribution": 4.067923545837402 }
  ]
}

エラーがツールの境界を越えて送出されることはありません。すべてのハンドラーが例外を捕捉し、代わりに構造化された ErrorResponse 辞書を返すため、呼び出し元のエージェントは常に解析可能な結果を受け取ります。

警告

NeuronScope は、モデルサイズ（デフォルトで 2B パラメーター、NEURONSCOPE_MAX_MODEL_PARAMS）と同時にロードできるモデル数（デフォルトで 1、NEURONSCOPE_MAX_CONCURRENT_LOADS）を制限しますが、モデルのロードやフォワードパスにはタイムアウトを設けていません。信頼できないエージェントが呼び出せる場所にこの MCP サーバーを公開する場合は、プロセスにリソース制限（cgroup、ulimit、またはコンテナーのメモリー／CPU 上限）を設けてください。プロセス内の制限だけに頼るのではなく、多層防御として対策する必要があります。

トランスポートは stdio なので、ホストする必要はありません。MCP クライアントがローカルのサブプロセスとしてサーバーを起動します。ソース： neuronscope/mcp_server.py。

• Claude Code は、リポジトリのルートにあるプロジェクトレベルの .mcp.json を読み込みます。または、claude mcp add neuronscope -- neuronscope-mcp で追加できます。
• Claude Desktop は、claude_desktop_config.json（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json）の同じ "mcpServers" キーの下にある設定を読み込みます。
• neuronscope mcp-server CLI サブコマンドも、既存のインストールから stdio 経由で同じサーバーを実行する、ローカルで uvx を使わない代替手段として引き続き利用できます。

比較

これら5つはいずれも実在し、現在も積極的にメンテナンスされているプロジェクトで、それぞれ異なる役割を担っています。この表では、CLI／JSONエージェント出力の対応状況とモデルのカバレッジを比較しています。解釈可能性研究の深さについては比較していません。この点では、TransformerLens、nnsight、SAELens、circuit-tracer、NeuronpediaはいずれもNeuronScopeより成熟しています。以下のスター数、リリース情報、最終プッシュ日は、2026-08-03に各プロジェクトのGitHub APIから取得したもので、時間とともに変わります。最新の数値は各リポジトリを直接確認してください。

プロジェクト	スター数	最終活動	CLI	エージェントから呼び出し可能な構造化出力	モデルのカバレッジ
TransformerLens	3,750	v3.6.0を2026-07-28にリリース、2026-08-03にプッシュ	いいえ（Pythonライブラリ）	いいえ	事前学習済みチェックポイント／エイリアス249件（独自の公式リスト）
nnsight	1,014	v0.7.0を2026-05-05にリリース、2026-07-30にプッシュ	いいえ（Pythonライブラリ）	いいえ（テンソル／Pythonオブジェクトを返します）	あらゆるHuggingFaceまたはPyTorchモデルに汎用的に対応。固定リストはありません
circuit-tracer（Anthropicが作成。safety-research/circuit-tracerから移動）	2,882	v0.5.2を2026-07-18にリリース、2026-07-18にプッシュ	はい	JSONの帰属グラフをエクスポート。MCP サーバーはありません	固定のトランスコーダー許可リスト：Gemma-2（2B）、Gemma-3（270M-27B）、Llama-3.2（1B）、Llama-3.1（8B Instruct）、Qwen-3（0.6B-14B）、GPT-OSS（20B）
SAELens	1,492	v6.47.0を2026-07-28にリリース、2026-07-28にプッシュ	いいえ（Pythonライブラリ）	いいえ	あらゆるPyTorchモデルに汎用的に対応。最も深く統合されているのはTransformerLensです
Neuronpedia	1,093	継続的にデプロイ、タグはv1.0.795	いいえ（ホスト型ウェブアプリ＋REST API）	REST APIはJSONを返します。MCPアクセスは非公式のサードパーティー製ラッパー経由でのみ利用でき、公式リポジトリにはありません	TransformerLensのモデルテーブルから読み込めるモデル（GPT-2、Gemma-2、Llama、DeepSeekなど）
NeuronScope（本プロジェクト）	1	このコミット	はい	はい：すべてのコマンドで--jsonに対応し、同じスキーマを返すネイティブMCPサーバーも備えています	TransformerLensのHookedTransformer.from_pretrainedがサポートするモデルすべて：チェックポイント／エイリアス249件

NeuronScopeの違いを正直に言えば、範囲は限定的です。これらの中で、CLI、ネイティブMCPサーバー、バージョン管理されたJSONスキーマを1つのパッケージにまとめているのはNeuronScopeだけです。また、circuit-tracerのような固定のトランスコーダー許可リストに限定されず、TransformerLensがサポートするモデル全般に対応します。これらのプロジェクトより高機能でも、成熟しているわけでも、広く使われているわけでもありません。

NeuronScopeとは何か、なぜ存在するのか

TransformerLensは、モデルを読み込んでフック付きの順方向パスを実行するためのPython APIを提供します。研究用ノートブックには適したインターフェースです。一方、サブプロセス呼び出しを実行してJSONドキュメントを受け取るスクリプトや、MCP経由で呼び出せるツールを必要とするエージェントには適していません。NeuronScopeは、そうした後者のインターフェースを提供するために存在します。同じ基盤となる計算処理をラップし、CLIの実行やMCPツールの呼び出しに対して、Pythonオブジェクトグラフではなくスキーマバージョン付きのドキュメントを返します。

FAQ

TransformerLens、nnsight、SAELens、circuit-tracer、Neuronpediaの代替ですか？ いいえ。NeuronScopeはTransformerLensを直接基盤としており、TransformerLens自体が低レベルで既にできることを超える機能はありません。SAEのトレーニング（SAELens）、トランスコーダーを使った完全なパスパッチングによる回路の発見（circuit-tracer）、任意のPyTorchモデル向けのPythonネイティブなトレーシング用コンテキストマネージャー（nnsight）、閲覧可能な特徴データベースのホスティング（Neuronpedia）は行いません。TransformerLensの機能の一部をCLIおよびMCPで利用できるようにするラッパーです。

どのモデルに対応していますか？ transformer_lens.HookedTransformer.from_pretrainedが対応するすべてのモデルです。現在は、GPT-2、Pythia、Llama、Gemma、Qwenなどを含む249個のチェックポイントとエイリアスに対応しています。TransformerLensではモデルが随時追加されるため、インストール済みのバージョンでの正確な数を確認するには、ご自身の環境で次を実行してください。 python -c "from transformer_lens.loading_from_pretrained import OFFICIAL_MODEL_NAMES; print(len(OFFICIAL_MODEL_NAMES))"

GPUは必要ですか？ いいえ。gpt2などの小さなモデルはCPUで問題なく動作します。上記のテストスイートとクイックスタートもCPUで実行します。大きなモデルはCPUでは遅くなります。NeuronScopeは、利用可能な場合でもApple SiliconのMPSバックエンドを自動選択しません。このプロジェクトのアクティベーションパッチングの計算では正確さが不可欠ですが、PyTorchのMPSバックエンドでは、一部の演算で誤った値がひそかに生成される可能性があるためです。それでも使用する場合は、ご自身のコードでdevice="mps"を明示的に指定してください。

信頼できないエージェントにMCPサーバーを公開しても安全ですか？ リソース制限を設けた場合に限ります。以下の「既知の制限」を参照してください。

NeuronScopeは、このリストにあるもう1つのCLIツール、circuit-tracerとどう違いますか？ circuit-tracerは、より詳細な回路分析（トレーニング済みトランスコーダーによる完全なアトリビューショングラフ）を行えますが、対応モデルは固定の許可リスト（Gemma-2、Gemma-3、Llama-3.1/3.2、Qwen-3、GPT-OSS）のみです。NeuronScopeはその詳細さを幅広さと引き換えにしています。トランスコーダーのトレーニング工程なしでTransformerLensが対応する249個のチェックポイントすべてで動作し、エージェントが直接呼び出せるMCPサーバーも備えています。その代わり、NeuronScopeが行うのは単一コンポーネントのロジットアトリビューションとゼロアブレーションであり、トランスコーダーを用いたパスパッチングではありません。

インストールしたバージョンは常にPyPI上のバージョンと一致しますか？ インストール後にneuronscope --versionを実行して確認してください。pip install neuronscope-cliを実行すると、PyPIで直近に公開されたリリースがインストールされます。リリース間は、このリポジトリのmainブランチのコードがPyPIの公開内容より先行している場合があります。ソースからインストール（pip install -e .）すると、未リリースの内容も含めて常にmainと正確に一致します。

NeuronScopeのライセンスは何ですか？商用利用できますか？ MITです。著作権表示とライセンス通知を保持すれば、商用プロジェクトやクローズドソースのプロジェクトで使用、変更、再配布できます。依存関係として導入されるもの（TransformerLens、PyTorch、mcpパッケージ）にはそれぞれ独自のライセンスがあります。neuronscope-cliを依存関係として呼び出すだけでなく、依存関係を同梱した製品を再配布する場合は、それらのライセンスも個別に確認してください。

既知の制限事項

• circuit は近似です。 1 つのプロンプトに対して、ロジット帰属度でコンポーネントをランク付けし、単一コンポーネントをゼロアブレーションして、それぞれの個別の因果効果を測定します。クリーン／破損プロンプトのペアを使った完全なパスパッチングは行わず、コンポーネント間の相互作用による効果も検出できません。--json の出力では method フィールドにこの点が記載されるため、呼び出し側は説明文を信頼しなくても注意事項を把握できます。
• モデルの読み込みや順伝播にはタイムアウトがありません。 以下のリソース上限を超えないリクエストは、組み込みの実時間制限なしで読み込みと順伝播が完了するまで実行されます。信頼できないエージェントが呼び出せる場所で MCP サーバーを実行する場合は、多層防御として、プロセスにリソース制限（cgroup、ulimit、またはコンテナのメモリ／CPU 上限）を設定してください。
• モデルサイズと読み込みの並行数には上限がありますが、プロセス内でのみ適用されます。 neuronscope/core/limits.py は、モデルの重みをダウンロードする前に NEURONSCOPE_MAX_MODEL_PARAMS（デフォルトでは 2B パラメーター）を超えるモデルを拒否し、さらに、他の読み込みが NEURONSCOPE_MAX_CONCURRENT_LOADS（デフォルトでは 1）件進行中の場合は、構造化エラーを返して読み込みを拒否します。ハングやクラッシュにはなりません。サイズチェックはベストエフォートです。たとえば、完全にオフラインでキャッシュもまだない場合など、モデルのパラメーター数を特定できない場合は、正当なリクエストを妨げないよう拒否せずに処理を続けます。そのため、これ単体では厳密な保証にはなりません。信頼できない環境にデプロイする場合は、プロセスレベルのリソース制限も併用してください。
• HookedTransformer.from_pretrained は上流で非推奨になっています。 TransformerLens 3.6.0 は、代替として TransformerBridge.boot_transformers を示す DeprecationWarning を出力します。現在も動作し、この README に記載されているすべてのコマンドはこれを使って実行されていますが、NeuronScope のバックエンドはまだ移行していません。未完了の項目として管理されています。移行する場合、変更箇所は neuronscope/backends/transformer_lens.py 内であり、CLI コマンドや MCP ツールのシグネチャは変更されません。

コントリビューション

Issue とプルリクエストを歓迎します。開発環境のセットアップ、コードの場所、プルリクエストのマージに必要な条件については、CONTRIBUTING.md を参照してください。概要は次のとおりです。

pip install -e ".[dev,mcp]"
pytest -v

CI では、main に対するすべてのプッシュとプルリクエストで、Python 3.10、3.11、3.12 を使って同じテストスイートを実行します。テストスイートは neuronscope/ の 87% をカバーします（pytest --cov=neuronscope）。主なカバー漏れは、MCP サーバーであまり実行されないパス（特定のエラー分岐）です。

ライセンス

MIT です。LICENSE を参照してください。