NeuronScope

NeuronScope

Pergunte a um modelo de linguagem "por que você disse isso" e receba de volta os cabeçalhos de atenção e neurônios reais responsáveis, em JSON, pela linha de comando ou por um agente via MCP.

Instalação

pip install neuronscope-cli

Isso fornece o comando neuronscope. Para instalar a partir do código-fonte (para desenvolvimento ou para acompanhar o main):

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

[!NOTE] A primeira execução de qualquer comando baixa o modelo solicitado do HuggingFace Hub (gpt2 tem cerca de 500MB) e imprime duas linhas em stderr que são esperadas, não erros: um aviso de fallback de CPU se você não tiver uma GPU CUDA, e um aviso de limite de taxa do HF Hub não autenticado. Nenhum dos dois significa que algo quebrou.

Início rápido

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

Saída real deste comando exato (stderr reduzido aos dois avisos esperados mencionados acima):

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 prevê Tokyo corretamente, e o cabeçalho L9H8 é o maior contribuinte individual para essa previsão. Adicione --json para obter a versão legível por máquina do mesmo resultado:

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 }
  ]
}

O que faz

NeuronScope é um servidor CLI e MCP construído sobre TransformerLens. O TransformerLens faz o carregamento real do modelo, os hooks e a matemática de ativação; o NeuronScope adiciona uma CLI estável, um esquema JSON versionado e um servidor MCP ao redor disso, para que um script ou agente possa perguntar "quais componentes impulsionaram esta saída" sem escrever código TransformerLens diretamente.

• trace: executa um prompt pelo modelo e classifica cabeçalhos de atenção por atribuição direta de logit ao token previsto, e neurônios MLP por magnitude de ativação na posição final do prompt.
• activations: despeja forma, média, desvio padrão, mínimo/máximo e a posição da sequência com maior ativação para o stream residual de cada camada, ativações de neurônios MLP e padrão de atenção.
• patch: faz zero-ablação de um componente (resid_pre, resid_mid, resid_post, attn_out, mlp_out ou mlp_post) em uma determinada camada e relata como o token previsto e seu logit mudaram.
• circuit: um esboço de circuito automatizado de melhor esforço. Classifica cabeçalhos/neurônios candidatos por atribuição de logit e depois mede o efeito causal individual de cada um via ablação de componente único. Isso não é path-patching completo com pares de prompts limpos/corrompidos e não captura efeitos de interação entre componentes. A saída --json diz isso explicitamente em seu campo method.
• Todo comando suporta --json para um documento com carimbo de schema_version em vez de uma tabela, e as mesmas quatro operações são expostas como ferramentas MCP retornando a mesma forma via .model_dump(), então uma chamada CLI e uma chamada de ferramenta MCP produzem o mesmo documento para a mesma entrada.
• O suporte a modelos é o que o transformer_lens.HookedTransformer.from_pretrained suporta. Instalar o neuronscope-cli hoje puxa o TransformerLens 3.6.0, que suporta 249 checkpoints e aliases pré-treinados (OFFICIAL_MODEL_NAMES), cobrindo GPT-2, Pythia, Llama, Gemma, Qwen e mais. Modelos pequenos como gpt2 rodam confortavelmente em CPU.

O NeuronScope não substitui o TransformerLens, nnsight, SAELens, o circuit-tracer da Anthropic ou Neuronpedia. Ele envolve o TransformerLens para um trabalho mais restrito: rastreamento rápido de componentes, scriptável e chamável por agentes em um único prompt. Ele deixa trabalhos mecanísticos mais profundos (treinamento de SAE, grafos de circuito baseados em transcoder, navegação de features hospedadas) para essas ferramentas.

Referência da CLI

Todo comando aceita MODEL (qualquer nome que o HookedTransformer.from_pretrained aceite, por exemplo gpt2 ou EleutherAI/pythia-70m) e PROMPT como argumentos posicionais.

Comando	Flags extras	O que faz
neuronscope trace MODEL PROMPT	--top-k INTEGER (padrão 10), --json	Classifica os principais cabeçalhos de atenção (atribuição de logit) e neurônios MLP (magnitude de ativação) para o próximo token previsto
neuronscope activations MODEL PROMPT	--json	Despeja estatísticas resumidas de ativação por camada (stream residual, MLP, padrão de atenção)
neuronscope patch MODEL PROMPT	--layer INTEGER (obrigatório), --component [resid_pre|resid_mid|resid_post|attn_out|mlp_out|mlp_post] (obrigatório), --json	Faz zero-ablação de um componente e relata o delta de logit/previsão
neuronscope circuit MODEL PROMPT	--top-k INTEGER (padrão 10), --json	Esboço de circuito de melhor esforço via ablação de componente único classificada
neuronscope mcp-server	nenhuma	Inicia o servidor MCP via stdio

Global: neuronscope --version, neuronscope <command> --help. Códigos de saída: 0 sucesso, 1 um erro de runtime (prompt longo demais para a janela de contexto do modelo, --layer fora do intervalo, etc.), 2 um erro de uso do Click (flags inválidas), 3 um nome de modelo não suportado.

Servidor MCP

O NeuronScope inclui um servidor Model Context Protocol para que um agente de IA (Claude, Cursor ou qualquer cliente compatível com MCP) possa rastrear, inspecionar, ablacionar e esboçar circuitos diretamente, sem que um humano invoque a CLI manualmente.

Instale o extra:

pip install "neuronscope-cli[mcp]"

Adicione-o à configuração do seu cliente MCP (para Claude Desktop, claude_desktop_config.json):

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

O servidor expõe quatro ferramentas, trace, activations, patch e circuit, cada uma retornando o mesmo JSON em formato de modelo pydantic que a flag --json da CLI imprime, via .model_dump(), então um agente chamando este servidor e um script chamando a CLI obtêm o mesmo documento para a mesma entrada. Uma chamada real de trace e sua resposta:

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 }
  ]
}

Erros nunca atravessam a fronteira da ferramenta: cada handler captura suas exceções e retorna um dict estruturado ErrorResponse em vez disso, então um agente chamador sempre obtém um resultado analisável.

[!WARNING] O NeuronScope não impõe limite de tamanho ou timeout no carregamento de modelos ou passes forward. Se você expor este servidor MCP em algum lugar onde um agente não confiável possa chamá-lo, coloque um limite de recursos ao redor do processo (um cgroup, ulimit ou um limite de memória/CPU de contêiner) em vez de confiar no NeuronScope para recusar uma solicitação excessivamente grande por conta própria.

O transporte é stdio, então não há nada para hospedar: o cliente MCP inicia o servidor como um subprocesso local. Fonte: neuronscope/mcp_server.py.

• Claude Code lê isso de um .mcp.json no nível do projeto na raiz do seu repositório, ou você pode adicioná-lo com claude mcp add neuronscope -- neuronscope-mcp.
• Claude Desktop lê isso do seu claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json no macOS, %APPDATA%\Claude\claude_desktop_config.json no Windows), sob a mesma chave "mcpServers".
• O subcomando CLI neuronscope mcp-server ainda funciona como uma alternativa local, não-uvx, que executa o mesmo servidor via stdio a partir de uma instalação existente.

Como se compara

Todos os cinco são projetos reais e ativamente mantidos que fazem trabalhos diferentes. Esta tabela compara a superfície de saída CLI/JSON para agentes e a cobertura de modelos, não a profundidade da pesquisa de interpretabilidade, onde TransformerLens, nnsight, SAELens, circuit-tracer e Neuronpedia são todos mais maduros que o NeuronScope. Contagens de estrelas, informações de versão e datas do último push abaixo foram obtidas da API do GitHub de cada projeto em 2026-08-03 e mudarão com o tempo; verifique os repositórios diretamente para números atuais.

Projeto	Estrelas	Última atividade	CLI	Saída estruturada chamável por agentes	Cobertura de modelos
TransformerLens	3.750	v3.6.0 lançado em 2026-07-28, push em 2026-08-03	Não (biblioteca Python)	Não	249 checkpoints/aliases pré-treinados (sua própria lista oficial)
nnsight	1.014	v0.7.0 lançado em 2026-05-05, push em 2026-07-30	Não (biblioteca Python)	Não (retorna tensores/objetos Python)	Qualquer modelo HuggingFace ou PyTorch genericamente, sem lista fixa
circuit-tracer (de autoria da Anthropic, movido de safety-research/circuit-tracer)	2.882	v0.5.2 lançado em 2026-07-18, push em 2026-07-18	Sim	Exportação de grafo de atribuição JSON; sem servidor MCP	Lista fixa de transcoders: 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 lançado em 2026-07-28, push em 2026-07-28	Não (biblioteca Python)	Não	Qualquer modelo PyTorch genericamente; integração mais profunda com TransformerLens
Neuronpedia	1.093	implantação contínua, tag v1.0.795	Não (aplicativo web hospedado + API REST)	A API REST retorna JSON; acesso MCP existe apenas via wrapper de terceiros não oficial, não no repositório oficial	Modelos carregáveis pela tabela de modelos do TransformerLens (GPT-2, Gemma-2, Llama, DeepSeek, etc.)
NeuronScope (este projeto)	1	este commit	Sim	Sim: --json em todo comando, além de um servidor MCP nativo retornando o mesmo esquema	O que o HookedTransformer.from_pretrained do TransformerLens suporta: 249 checkpoints/aliases

A diferenciação honesta é estreita: o NeuronScope é o único destes com uma CLI, um servidor MCP nativo e um esquema JSON versionado juntos em um único pacote, e é agnóstico de modelos em tudo o que o TransformerLens suporta, em vez de fixado a uma lista fixa de transcoders como o circuit-tracer. Ele não é mais capaz, mais maduro ou mais amplamente usado do que qualquer um desses projetos.

O que é o NeuronScope e por que ele existe

O TransformerLens fornece uma API Python para carregar um modelo e executar passes forward com hooks. Essa é a interface certa para um notebook de pesquisa. É a interface errada para um script que precisa de uma chamada de subprocesso e um documento JSON de volta, ou para um agente que precisa de uma ferramenta que possa chamar via MCP. O NeuronScope existe para ser essa segunda interface: o mesmo cálculo subjacente, envolvido para que uma invocação CLI ou uma chamada de ferramenta MCP retorne um documento com esquema versionado em vez de um grafo de objetos Python.

FAQ

Isso é um substituto para TransformerLens, nnsight, SAELens, circuit-tracer ou Neuronpedia? Não. O NeuronScope é construído diretamente sobre o TransformerLens e não faz nada que o TransformerLens já não possa fazer em um nível mais baixo. Ele não treina SAEs (SAELens), não faz descoberta de circuitos com path-patching completo usando transcoders (circuit-tracer), não fornece um gerenciador de contexto de rastreamento nativo em Python para modelos PyTorch arbitrários (nnsight) nem hospeda um banco de dados de features navegável (Neuronpedia). É um wrapper CLI e MCP em torno de uma fatia da funcionalidade do TransformerLens.

Quais modelos são suportados? Qualquer coisa que o transformer_lens.HookedTransformer.from_pretrained suporta, que hoje são 249 checkpoints e aliases abrangendo GPT-2, Pythia, Llama, Gemma, Qwen e outros. Execute python -c "from transformer_lens.loading_from_pretrained import OFFICIAL_MODEL_NAMES; print(len(OFFICIAL_MODEL_NAMES))" no seu próprio ambiente para obter a contagem exata para a sua versão instalada, já que o TransformerLens adiciona modelos ao longo do tempo.

Precisa de GPU? Não. Modelos pequenos como gpt2 rodam bem em CPU; é nisso que a suíte de testes e o início rápido acima rodam. Modelos maiores serão lentos em CPU. O NeuronScope não seleciona automaticamente o backend MPS do Apple Silicon mesmo quando disponível, porque o backend MPS do PyTorch pode silenciosamente produzir valores incorretos para algumas operações das quais a matemática de path-patching deste projeto depende para ser exata. Passe device="mps" explicitamente no seu próprio código se quiser mesmo assim.

É seguro expor o servidor MCP a um agente não confiável? Somente com limites de recursos em vigor. Veja Limitações conhecidas abaixo. Como o NeuronScope é diferente do circuit-tracer, a outra ferramenta CLI desta lista? O circuit-tracer faz uma análise de circuitos mais profunda (gráficos de atribuição completos a partir de transcoders treinados), mas apenas para uma lista fixa de modelos: Gemma-2, Gemma-3, Llama-3.1/3.2, Qwen-3 e GPT-OSS. O NeuronScope troca essa profundidade por amplitude: ele funciona com qualquer um dos 249 checkpoints suportados pelo TransformerLens, sem etapa de treinamento de transcoder, e inclui um servidor MCP para que um agente possa chamá-lo diretamente. O custo é que o NeuronScope faz atribuição de logits de componente único e zero-ablation, e não path patching baseado em transcoder.

A versão instalada sempre corresponde ao que está no PyPI? Execute neuronscope --version após a instalação para verificar. pip install neuronscope-cli baixa a versão mais recente publicada no PyPI; o código no branch main deste repositório pode estar à frente disso entre as versões. Instalar a partir do código-fonte (pip install -e .) sempre acompanha main exatamente, incluindo o que ainda não foi lançado.

Sob qual licença está o NeuronScope e posso usá-lo comercialmente? MIT. Você pode usar, modificar e redistribuir em projetos comerciais e de código fechado, mantendo a atribuição e o aviso de licença intactos. As dependências que ele traz (TransformerLens, PyTorch, o pacote mcp) têm suas próprias licenças; verifique-as separadamente se você estiver redistribuindo um produto empacotado em vez de apenas chamar neuronscope-cli como dependência.

Limitações conhecidas

• circuit é uma aproximação. Ele classifica os componentes por atribuição de logits e mede o efeito causal individual de cada um via zero-ablation de componente único em um prompt. Ele não faz path patching completo com pares de prompts limpos/corrompidos e não captura efeitos de interação entre componentes. A saída de --json declara isso no campo method para que quem chama não precise confiar em texto corrido para saber da ressalva.
• Sem limite de tamanho ou timeout no carregamento de modelos ou forward passes. O NeuronScope carrega os pesos do modelo que o chamador solicitar e executa o forward pass até a conclusão, sem limite embutido de tamanho do modelo ou tempo de execução. Se você executar o servidor MCP em um local onde um agente não confiável possa chamá-lo, coloque um limite de recursos em torno do processo (um cgroup, ulimit ou um limite de memória/CPU do contêiner) em vez de depender do NeuronScope para recusar uma solicitação excessivamente grande por conta própria.
• HookedTransformer.from_pretrained está obsoleto upstream. O TransformerLens 3.6.0 emite um DeprecationWarning apontando para TransformerBridge.boot_transformers como substituto. Ainda funciona hoje, e todos os comandos mostrados neste README foram executados nele, mas o backend do NeuronScope ainda não migrou. Rastreado como item em aberto; a migração seria uma mudança dentro de neuronscope/backends/transformer_lens.py, não uma mudança em nenhum comando CLI ou assinatura de ferramenta MCP.

Contribuindo

Issues e pull requests são bem-vindos. Veja CONTRIBUTING.md para a configuração de desenvolvimento, onde o código está e o que um PR precisa antes de ser mesclado. Versão rápida:

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

O CI executa a mesma suíte em Python 3.10, 3.11 e 3.12 em cada push e pull request contra main. A suíte cobre 87% de neuronscope/ (pytest --cov=neuronscope), sendo os caminhos menos exercitados do servidor MCP (ramos de erro específicos) a principal lacuna.

Licença

MIT. Veja LICENSE.