NeuronScope

NeuronScope

Pergunte a um modelo de linguagem "por que você disse isso" e receba 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 ele faz

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

• trace: executa um prompt pelo modelo e classifica os 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, min/máx e a posição da sequência de ativação máxima para o stream residual de cada camada, ativações de neurônios MLP e padrão de atenção.
• patch: zera a 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, em seguida, 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 de componentes rápido, scriptável e chamável por agente 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 ele 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	Zera a 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 tempo de execução (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 o limite 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 limita o tamanho do modelo (2B parâmetros por padrão, NEURONSCOPE_MAX_MODEL_PARAMS) e quantos modelos podem ser carregados de uma vez (1 por padrão, NEURONSCOPE_MAX_CONCURRENT_LOADS), mas não coloca timeout no carregamento de modelos ou em passagens forward. Se você expor este servidor MCP em algum lugar onde um agente não confiável possa chamá-lo, ainda coloque um limite de recursos em torno do processo (um cgroup, ulimit ou um limite de memória/CPU do contêiner) como defesa em profundidade, em vez de confiar apenas nesses limites em processo.

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 ele se compara

Todos os cinco são projetos reais, ativamente mantidos, fazendo trabalhos diferentes. Esta tabela compara a superfície de saída CLI/JSON-para-agente 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 lançamento 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 agente	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	Allowlist 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)	API REST retorna JSON; acesso MCP existe apenas via wrapper não oficial de terceiros, 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 desses com uma CLI, um servidor MCP nativo e um esquema JSON versionado juntos em um único pacote, e é agnóstico de modelo em tudo o que o TransformerLens suporta, em vez de fixado a uma allowlist 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 passagens 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 versão de esquema 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 com 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.

Ele 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 activation-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, 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 puxa qualquer versão que o PyPI tenha publicado mais recentemente; o código no branch main deste repositório pode estar à frente disso entre 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 o NeuronScope está e posso usá-lo comercialmente? MIT. Você pode usar, modificar e redistribuí-lo em projetos comerciais e de código fechado, com atribuição e aviso de licença mantidos intactos. As dependências que ele traz (TransformerLens, PyTorch, o pacote mcp) possuem 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 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 detectará efeitos de interação entre componentes. A saída --json declara isso em seu campo method para que um chamador não precise confiar em prosa para saber a ressalva.
• Sem timeout no carregamento do modelo ou nas passagens forward. Uma vez que uma solicitação passa pelos limites de recursos abaixo, o NeuronScope executa o carregamento e a passagem forward até a conclusão, sem limite de tempo de relógio embutido. Se você executar o servidor MCP em algum lugar 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) como defesa em profundidade.
• O tamanho do modelo e a concorrência de carregamento são limitados, mas apenas no processo. neuronscope/core/limits.py rejeita um modelo acima de NEURONSCOPE_MAX_MODEL_PARAMS (2B parâmetros por padrão) antes que qualquer peso seja baixado, e rejeita um carregamento quando NEURONSCOPE_MAX_CONCURRENT_LOADS (1 por padrão) outros carregamentos já estão em andamento, ambos com um erro estruturado em vez de um travamento ou falha. A verificação de tamanho é de melhor esforço: se a contagem de parâmetros de um modelo não puder ser determinada (por exemplo, totalmente offline sem nada em cache), ela falha aberto em vez de bloquear uma solicitação legítima, então não é uma garantia rígida por si só — combine-a com um limite de recursos no nível do processo para implantações não confiáveis.
• 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; migrar seria uma mudança dentro de neuronscope/backends/transformer_lens.py, não uma mudança em qualquer comando CLI ou assinatura de ferramenta MCP.

Contribuindo

Issues e pull requests são bem-vindos. Veja CONTRIBUTING.md para configuração de desenvolvimento, onde o código está localizado 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), com os caminhos menos exercitados do servidor MCP (branches de erro específicos) como a principal lacuna.

Licença

MIT. Veja LICENSE.