NeuronScope

NeuronScope

Pregúntale a un modelo de lenguaje "¿por qué dijiste eso?" y obtén los cabezales de atención y neuronas reales responsables, en JSON, desde la línea de comandos o desde un agente a través de MCP.

Instalación

pip install neuronscope-cli

Eso te da el comando neuronscope. Para instalar desde el código fuente en su lugar (para desarrollo o para seguir main):

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

[!NOTE] La primera ejecución de cualquier comando descarga el modelo solicitado desde el HuggingFace Hub (gpt2 pesa unos 500MB) e imprime dos líneas en stderr que son esperadas, no errores: un aviso de respaldo a CPU si no tienes una GPU CUDA, y un aviso de límite de tasa del HF Hub sin autenticación. Ninguno de los dos significa que algo se haya roto.

Inicio rápido

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

Salida real de este comando exacto (stderr recortado a las dos advertencias esperadas mencionadas arriba):

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 predice Tokyo correctamente, y el cabezal L9H8 es el mayor contribuyente individual a esa predicción. Añade --json para obtener la versión legible por máquina del mismo 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 }
  ]
}

Qué hace

NeuronScope es una CLI y un servidor MCP construido sobre TransformerLens. TransformerLens hace la carga real del modelo, el hooking y las matemáticas de activación; NeuronScope añade una CLI estable, un esquema JSON versionado y un servidor MCP a su alrededor, para que un script o un agente pueda preguntar "qué componentes impulsaron esta salida" sin escribir código de TransformerLens directamente.

• trace: ejecuta un prompt a través del modelo y clasifica los cabezales de atención por atribución directa de logits al token predicho, y las neuronas MLP por magnitud de activación en la posición final del prompt.
• activations: vuelca forma, media, desviación estándar, min/max y la posición de secuencia de máxima activación para el residual stream de cada capa, las activaciones de neuronas MLP y el patrón de atención.
• patch: ablaciona a cero un componente (resid_pre, resid_mid, resid_post, attn_out, mlp_out o mlp_post) en una capa dada e informa cómo cambió el token predicho y su logit.
• circuit: un esbozo de circuito automatizado de mejor esfuerzo. Clasifica cabezales/neuronas candidatos por atribución de logits, luego mide el efecto causal individual de cada uno mediante ablación de un solo componente. Esto no es path-patching completo con pares de prompts limpios/corruptos y no captura efectos de interacción entre componentes. La salida de --json lo dice explícitamente en su campo method.
• Cada comando soporta --json para un documento con marca de tiempo schema_version en lugar de una tabla, y las mismas cuatro operaciones se exponen como herramientas MCP que devuelven la misma forma vía .model_dump(), de modo que una llamada CLI y una llamada a herramienta MCP producen el mismo documento para la misma entrada.
• El soporte de modelos es lo que transformer_lens.HookedTransformer.from_pretrained soporta. Instalar neuronscope-cli hoy trae TransformerLens 3.6.0, que soporta 249 checkpoints y alias preentrenados (OFFICIAL_MODEL_NAMES), cubriendo GPT-2, Pythia, Llama, Gemma, Qwen y más. Modelos pequeños como gpt2 se ejecutan cómodamente en CPU.

NeuronScope no reemplaza a TransformerLens, nnsight, SAELens, el circuit-tracer de Anthropic, ni Neuronpedia. Envuelve a TransformerLens para un trabajo más acotado: trazado de componentes rápido, scripteable y llamable por agentes en un solo prompt. Deja el trabajo mecanicista más profundo (entrenamiento de SAE, grafos de circuitos basados en transcoders, navegación de features alojadas) a esas herramientas.

Referencia de CLI

Cada comando toma MODEL (cualquier nombre que HookedTransformer.from_pretrained acepte, por ejemplo gpt2 o EleutherAI/pythia-70m) y PROMPT como argumentos posicionales.

Comando	Flags adicionales	Qué hace
neuronscope trace MODEL PROMPT	--top-k INTEGER (por defecto 10), --json	Clasifica los cabezales de atención principales (atribución de logits) y las neuronas MLP (magnitud de activación) para el siguiente token predicho
neuronscope activations MODEL PROMPT	--json	Vuelca estadísticas resumidas de activación por capa (residual stream, MLP, patrón de atención)
neuronscope patch MODEL PROMPT	--layer INTEGER (requerido), --component [resid_pre|resid_mid|resid_post|attn_out|mlp_out|mlp_post] (requerido), --json	Ablaciona a cero un componente e informa el delta de logit/predicción
neuronscope circuit MODEL PROMPT	--top-k INTEGER (por defecto 10), --json	Esbozo de circuito de mejor esfuerzo mediante ablación de un solo componente clasificada
neuronscope mcp-server	ninguno	Inicia el servidor MCP sobre stdio

Global: neuronscope --version, neuronscope <command> --help. Códigos de salida: 0 éxito, 1 un error de ejecución (prompt demasiado largo para la ventana de contexto del modelo, --layer fuera de rango, etc.), 2 un error de uso de Click (flags incorrectos), 3 un nombre de modelo no soportado.

Servidor MCP

NeuronScope incluye un servidor Model Context Protocol para que un agente de IA (Claude, Cursor o cualquier cliente compatible con MCP) pueda trazar, inspeccionar, ablacionar y esbozar circuitos directamente, sin que un humano invoque la CLI manualmente.

Instala el extra:

pip install "neuronscope-cli[mcp]"

Añádelo a la configuración de tu cliente MCP (para Claude Desktop, claude_desktop_config.json):

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

El servidor expone cuatro herramientas, trace, activations, patch y circuit, cada una devolviendo el mismo JSON con forma de modelo pydantic que imprime el flag --json de la CLI, vía .model_dump(), de modo que un agente que llama a este servidor y un script que llama a la CLI obtienen el mismo documento para la misma entrada. Una llamada real a trace y su respuesta:

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

Los errores nunca se propagan a través del límite de la herramienta: cada handler captura sus excepciones y devuelve un dict ErrorResponse estructurado en su lugar, de modo que un agente que llama siempre obtiene un resultado analizable.

[!WARNING] NeuronScope limita el tamaño del modelo (2B parámetros por defecto, NEURONSCOPE_MAX_MODEL_PARAMS) y cuántos modelos pueden cargarse a la vez (1 por defecto, NEURONSCOPE_MAX_CONCURRENT_LOADS), pero no pone un timeout en la carga de modelos ni en los forward passes. Si expones este servidor MCP en algún lugar donde un agente no confiable pueda llamarlo, pon igualmente un límite de recursos alrededor del proceso (un cgroup, ulimit o un límite de memoria/CPU del contenedor) como defensa en profundidad en lugar de confiar solo en estos límites dentro del proceso.

El transporte es stdio, así que no hay nada que alojar: el cliente MCP lanza el servidor como un subproceso local. Fuente: neuronscope/mcp_server.py.

• Claude Code lee esto desde un .mcp.json a nivel de proyecto en la raíz de tu repo, o puedes añadirlo con claude mcp add neuronscope -- neuronscope-mcp.
• Claude Desktop lee esto desde su claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows), bajo la misma clave "mcpServers".
• El subcomando CLI neuronscope mcp-server sigue funcionando como una alternativa local, no-uvx, que ejecuta el mismo servidor sobre stdio desde una instalación existente.

Cómo se compara

Los cinco son proyectos reales, mantenidos activamente, que hacen trabajos diferentes. Esta tabla compara la superficie de salida CLI/JSON-para-agentes y la cobertura de modelos, no la profundidad de la investigación en interpretabilidad, donde TransformerLens, nnsight, SAELens, circuit-tracer y Neuronpedia son todos más maduros que NeuronScope. Los conteos de estrellas, la información de versiones y las fechas del último push a continuación se obtuvieron de la API de GitHub de cada proyecto el 2026-08-03 y cambiarán con el tiempo; revisa los repos directamente para obtener cifras actuales.

Proyecto	Estrellas	Última actividad	CLI	Salida estructurada llamable por agentes	Cobertura de modelos
TransformerLens	3,750	v3.6.0 lanzada 2026-07-28, push 2026-08-03	No (biblioteca de Python)	No	249 checkpoints/alias preentrenados (su propia lista oficial)
nnsight	1,014	v0.7.0 lanzada 2026-05-05, push 2026-07-30	No (biblioteca de Python)	No (devuelve tensores/objetos de Python)	Cualquier modelo de HuggingFace o PyTorch genéricamente, sin lista fija
circuit-tracer (de Anthropic, movido desde safety-research/circuit-tracer)	2,882	v0.5.2 lanzada 2026-07-18, push 2026-07-18	Sí	Exportación de grafo de atribución JSON; sin servidor MCP	Lista fija 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 lanzada 2026-07-28, push 2026-07-28	No (biblioteca de Python)	No	Cualquier modelo de PyTorch genéricamente; la integración más profunda es con TransformerLens
Neuronpedia	1,093	despliegue continuo, tag v1.0.795	No (aplicación web alojada + API REST)	La API REST devuelve JSON; el acceso MCP existe solo mediante un wrapper no oficial de terceros, no en el repo oficial	Modelos cargables a través de la tabla de modelos de TransformerLens (GPT-2, Gemma-2, Llama, DeepSeek, etc.)
NeuronScope (este proyecto)	1	este commit	Sí	Sí: --json en cada comando, más un servidor MCP nativo que devuelve el mismo esquema	Lo que soporte HookedTransformer.from_pretrained de TransformerLens: 249 checkpoints/alias

La diferenciación honesta es estrecha: NeuronScope es el único de estos con una CLI, un servidor MCP nativo y un esquema JSON versionado juntos en un solo paquete, y es agnóstico respecto al modelo en todo lo que TransformerLens soporta, en lugar de estar fijado a una lista fija de transcoders como circuit-tracer. No es más capaz, más maduro ni más ampliamente usado que ninguno de estos proyectos.

Qué es NeuronScope y por qué existe

TransformerLens te da una API de Python para cargar un modelo y ejecutar forward passes con hooks. Esa es la interfaz correcta para un notebook de investigación. Es la interfaz incorrecta para un script que necesita una llamada a un subproceso y un documento JSON de vuelta, o para un agente que necesita una herramienta que pueda llamar vía MCP. NeuronScope existe para ser esa segunda interfaz: el mismo cálculo subyacente, envuelto para que una invocación CLI o una llamada a herramienta MCP devuelva un documento con esquema versionado en lugar de un grafo de objetos de Python.

FAQ

¿Es esto un reemplazo para TransformerLens, nnsight, SAELens, circuit-tracer o Neuronpedia? No. NeuronScope está construido directamente sobre TransformerLens y no hace nada que TransformerLens no pueda hacer ya a un nivel más bajo. No entrena SAEs (SAELens), no hace descubrimiento de circuitos con path-patching completo con transcoders (circuit-tracer), no te da un context manager de trazado nativo de Python para modelos arbitrarios de PyTorch (nnsight) ni aloja una base de datos de features navegable (Neuronpedia). Es una CLI y un wrapper MCP alrededor de una porción de la funcionalidad de TransformerLens.

¿Qué modelos están soportados? Cualquier cosa que transformer_lens.HookedTransformer.from_pretrained soporte, que hoy son 249 checkpoints y alias que abarcan GPT-2, Pythia, Llama, Gemma, Qwen y otros. Ejecuta python -c "from transformer_lens.loading_from_pretrained import OFFICIAL_MODEL_NAMES; print(len(OFFICIAL_MODEL_NAMES))" en tu propio entorno para obtener el conteo exacto para tu versión instalada, ya que TransformerLens añade modelos con el tiempo.

¿Necesita una GPU? No. Modelos pequeños como gpt2 se ejecutan bien en CPU; eso es lo que la suite de pruebas y el inicio rápido de arriba usan. Modelos más grandes serán lentos en CPU. NeuronScope no selecciona automáticamente el backend MPS de Apple Silicon incluso cuando está disponible, porque el backend MPS de PyTorch puede silenciosamente producir valores incorrectos para algunas operaciones de las que depende el cálculo de path-patching de este proyecto para ser exacto. Pasa device="mps" explícitamente en tu propio código si lo quieres de todos modos.

¿Es seguro exponer el servidor MCP a un agente no confiable? Solo con límites de recursos en su lugar. Ver Limitaciones conocidas a continuación. ¿En qué se diferencia NeuronScope de circuit-tracer, la otra herramienta CLI en esta lista? circuit-tracer realiza un análisis de circuitos más profundo (gráficos de atribución completos a partir de transcodificadores entrenados), pero solo para una lista fija de modelos: Gemma-2, Gemma-3, Llama-3.1/3.2, Qwen-3 y GPT-OSS. NeuronScope intercambia esa profundidad por amplitud: funciona con cualquiera de los 249 checkpoints compatibles de TransformerLens sin necesidad de un paso de entrenamiento de transcodificador, e incluye un servidor MCP para que un agente pueda llamarlo directamente. El costo es que NeuronScope realiza atribución de logits de un solo componente y ablación cero, no parcheo de rutas basado en transcodificadores.

¿La versión instalada siempre coincide con la de PyPI? Ejecuta neuronscope --version después de instalar para verificarlo. pip install neuronscope-cli obtiene la versión que PyPI haya publicado más recientemente; el código en la rama main de este repositorio puede estar por delante de eso entre versiones. Instalar desde el código fuente (pip install -e .) siempre sigue main exactamente, incluyendo lo que aún no se haya publicado.

¿Bajo qué licencia está NeuronScope y puedo usarlo comercialmente? MIT. Puedes usarlo, modificarlo y redistribuirlo en proyectos comerciales y de código cerrado, manteniendo la atribución y el aviso de licencia intactos. Las dependencias que incorpora (TransformerLens, PyTorch, el paquete mcp) tienen sus propias licencias; verifícalas por separado si estás redistribuyendo un producto empaquetado en lugar de solo llamar a neuronscope-cli como dependencia.

Limitaciones conocidas

• circuit es una aproximación. Clasifica los componentes por atribución de logits y mide el efecto causal individual de cada uno mediante ablación cero de un solo componente en un prompt. No realiza parcheo de rutas completo con pares de prompts limpios/corruptos, y no detectará efectos de interacción entre componentes. La salida de --json lo indica en su campo method para que quien lo llame no tenga que confiar en la prosa para conocer la advertencia.
• Sin tiempo de espera en la carga del modelo ni en los pases hacia adelante. Una vez que una solicitud supera los límites de recursos indicados a continuación, NeuronScope ejecuta la carga y el pase hacia adelante hasta completarse sin límite de tiempo de reloj integrado. Si ejecutas el servidor MCP en un lugar donde un agente no confiable pueda llamarlo, coloca un límite de recursos alrededor del proceso (un cgroup, ulimit o un límite de memoria/CPU del contenedor) como defensa en profundidad.
• El tamaño del modelo y la concurrencia de carga están limitados, pero solo dentro del proceso. neuronscope/core/limits.py rechaza un modelo mayor a NEURONSCOPE_MAX_MODEL_PARAMS (2B parámetros por defecto) antes de que se descarguen los pesos, y rechaza una carga una vez que NEURONSCOPE_MAX_CONCURRENT_LOADS (1 por defecto) otras cargas ya están en curso, ambas con un error estructurado en lugar de un bloqueo o un fallo. La verificación de tamaño es de mejor esfuerzo: si no se puede determinar el número de parámetros de un modelo (por ejemplo, completamente sin conexión y sin nada en caché), falla abiertamente en lugar de bloquear una solicitud legítima, por lo que no es una garantía estricta por sí sola: combínala con un límite de recursos a nivel de proceso para implementaciones no confiables.
• HookedTransformer.from_pretrained está obsoleto en el upstream. TransformerLens 3.6.0 emite un DeprecationWarning que apunta a TransformerBridge.boot_transformers como reemplazo. Todavía funciona hoy, y todos los comandos mostrados en este README se ejecutaron con él, pero el backend de NeuronScope aún no ha migrado. Se registra como un elemento pendiente; migrar sería un cambio dentro de neuronscope/backends/transformer_lens.py, no un cambio en ningún comando CLI ni en la firma de las herramientas MCP.

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Consulta CONTRIBUTING.md para la configuración de desarrollo, dónde vive el código y qué necesita un PR antes de fusionarse. Versión rápida:

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

CI ejecuta la misma suite en Python 3.10, 3.11 y 3.12 en cada push y pull request contra main. La suite cubre el 87% de neuronscope/ (pytest --cov=neuronscope), siendo las rutas menos ejercitadas del servidor MCP (ramas de error específicas) la principal brecha.

Licencia

MIT. Consulta LICENSE.