neuronpedia

The Problem

Machine‑learning researchers need a unified UI/API to explore model activations, steer generation, and run interpretability pipelines. Building such a stack from scratch requires wiring a Python inference service, a graph server, a React front‑end, and a set of utility scripts for data export – all while keeping the pieces testable and container‑ready.

What This Does

neuronpedia is a monorepo that bundles four self‑contained services:

• apps/autointerp – FastAPI server that receives activation requests, calls a language model (model.generate) and returns scored explanations. Entry point: apps/autointerp/server.py.
• apps/inference – Core inference API exposing endpoints for persona‑driven chat, SAE (Sparse Auto‑Encoder) handling, and batch activation export. Entry point: apps/inference/neuronpedia_inference/server.py.
• apps/graph – Graph‑generation microservice that builds circuit visualisations and talks to external storage via HTTP (requests.put). Entry point: apps/graph/neuronpedia_graph/server.py.
• apps/experiments/steerify – A Next.js + Tailwind front‑end (TSX) that demos steering UI; built with npm/next.

Common libraries live under packages/ (TypeScript inference client, Python web‑app client, autointerp client) and utils/ (batch‑autointerp, export‑data). Dockerfiles for each service and a Kubernetes manifest directory (k8s/) enable cloud deployment.

How It Is Wired

Execution starts at the concrete entry points:

Typical request flow (e.g., an activation scoring call):

1. HTTP request → FastAPI endpoint in apps/autointerp/neuronpedia_autointerp/routes/score/embedding.py.
2. Calls call_api (called from 45 places) → internal helper response_deserialize (30 places) → model.generate (external model call, see “What this touches outside itself”).
3. Result passes through to_json / to_dict (each called >50 times) before being returned.
4. Shared utilities such as apps/inference/neuronpedia_inference/sae_manager.py:get_instance are invoked by 14 other files, making them high‑blast‑radius modules.

The most connected module is packages/typescript/neuronpedia-inference-client/src/models/index (45 inbound, 2 outbound imports, instability 0.96). Its volatility affects many TypeScript consumers. A circular import exists among apps/webapp/app/sae-bench/evals-table.tsx, evals-plot.tsx, and evals-table-presets.tsx, inflating coupling and risk of breakage.

All outbound effects are mapped:

• Model inference – model.generate invoked from startup_event → preload_model and from async_handler → _generate_both_types.
• Network – requests.put in apps/graph/runpod-gemma-2-2b/rp_handler.py:graph_generation_handler.
• Filesystem – os.makedirs in apps/inference/neuronpedia_inference/server.py:main -> process_data.
• Database – utils/neuronpedia-utils/export-data.py writes/reads SQLite (single call).

How To Use It

# Clone (use the exact URL from the spec)
git clone https://github.com/moses-y/neuronpedia
cd neuronpedia

# Install Python services (Poetry)
cd apps/autointerp
poetry install   # reads apps/autointerp/pyproject.toml
# Repeat for other Python apps (inference, graph) as needed

# Build and run a service with Docker (example: autointerp)
docker build -t neuronpedia-autointerp -f apps/autointerp/Dockerfile .
docker run -p 8000:8000 --env-file .env.inference.deepseek-r1-distill-llama-8b.llamascope-slimpj-res-32k neuronpedia-autointerp

# Front‑end dev (steerify)
cd apps/experiments/steerify
npm ci           # lockfile present
npm run dev      # starts Next.js on localhost

Required secrets are read from the .env.* files listed in the repo root (e.g., API keys for OpenAI). Copy the example .env.example files, fill in real values, and ensure the files stay ignored by Git.

Real‑World Use

A research team can spin up the inference service locally, point their Jupyter notebooks at http://localhost:8000/api/activation, and feed the results to the React dashboard (apps/experiments/steerify) for interactive steering. The same endpoints can be containerised and deployed via the provided Kubernetes manifests for production workloads.

Code Health & Issues

• High – .env.inference.deepseek-r1-distill-llama-8b.llamascope-slimpj-res-32k tracked despite .gitignore. git rm --cached and rotate credentials.
• High – GitHub Actions use mutable tags (snok/install-poetry@v1, softprops/action-gh-release@v1). Pin to SHA.
• High – Committed .env files expose live secrets. Remove, add to .gitignore, rotate, and commit an .env.example.
• High – Wildcard CORS (allow_origins=["*"]) in apps/inference/neuronpedia_inference/server.py. Replace with explicit origins.
• Medium – No least‑privilege GITHUB_TOKEN permissions in .github/workflows/autointerp-tests.yml. Add permissions: contents: read.
• Medium – No Dependabot/Renovate configuration. Add .github/dependabot.yml.
• Medium – CI installs npm dependencies with npm install instead of npm ci. Switch to npm ci.
• Medium – Base images in Dockerfiles are mutable tags (python:3.10-slim, CUDA). Pin by digest.
• Medium – No dependency‑vulnerability scan in CI. Add dependency-review-action or osv-scanner.
• Medium – No pre‑commit secret‑scan hook. Install a secret‑scanning hook (e.g., detect-secrets).
• Low – (two additional low‑severity findings omitted for brevity; see full audit report).

Overall, the repository ships a functional, well‑tested stack with CI, Docker, and a rich test suite, but it contains several production‑readiness gaps around secret handling, CI reproducibility, and module coupling.

The Bottom Line

neuronpedia delivers a complete, container‑ready interpretability platform; its modular services and extensive test coverage are strengths. However, the high‑blast‑radius hub modules, circular imports, and security hygiene issues (exposed .env files, mutable CI actions) require remediation before a production deployment. Engineers comfortable with Python FastAPI, Next.js, and Docker will find the codebase approachable, but should address the listed high‑severity findings early.