---
title: NeuroScope API
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# NeuroScope API

FastAPI + TransformerLens backend for the NeuroScope interpretability toolkit.

Exposes activation-extraction endpoints (logit lens, attention patterns, gradient-based token importance, steering vectors, PCA trajectories) plus the Refusal Bench (six published refusal-ablation techniques scored against a shared harmfulness probe) for the NeuroScope frontend.

## Endpoints

| Endpoint | Purpose |
|---|---|
| `POST /load` | Load a model from the whitelist (default: `gpt2-small`) |
| `POST /logit-lens` | Layer-by-layer next-token predictions |
| `POST /attention` | Attention pattern for a given (layer, head) |
| `POST /gradients` | Token-level gradient magnitudes w.r.t. a target token |
| `POST /steering-vector` | Difference-of-means vector from contrastive prompts |
| `POST /generate-steered` | Generation with a steering vector injected at a layer |
| `POST /ablate-direction` | Generation with a direction projected out of the residual stream (`h' = h − (h·d̂)d̂`) |
| `POST /patch` | Activation-patching sweep over (layer × position) or (layer × head); denoising = sufficiency, noising = necessity |
| `POST /harmfulness-probe` | Train a Zhao-style linear harmfulness probe on residuals at a layer; optionally re-evaluate it under ablation |
| `POST /refusal-bench` | Run the Refusal Bench end-to-end: one row per requested technique, scored by refusal rate + probe AUC (optional `over_refusal_prompts` for techniques that need an over-refusal split, e.g. Maskey) |
| `GET /refusal-bench/techniques` | List the registered refusal-ablation techniques |
| `POST /pca-trajectories` | 3D PCA of residual stream across layers + tokens |
| `GET /contrastive-pairs` | Built-in sentiment contrastive prompt pairs |
| `GET /refusal-pairs` | Curated refusal-direction contrastive pairs (harmful + harmless) |

Interactive docs at `/docs` once the Space is live.

## Supported models

Model loading is restricted to a whitelist (no arbitrary HF pulls):

- `gpt2-small` — default, ungated
- `meta-llama/Llama-3.2-1B-Instruct` — gated; requires `HF_TOKEN`
- `meta-llama/Llama-3.2-3B-Instruct` — gated; requires `HF_TOKEN`

## Configuration

Set the following Space Variables/Secrets in **Settings → Variables and secrets**:

- `ALLOWED_ORIGINS` — comma-separated CORS origins (e.g. `https://neuroscope.vercel.app,http://localhost:3001`)
- `HF_TOKEN` (secret) — HuggingFace token with access to the gated Llama-3.2 models; not needed for GPT-2

## Local development

```bash
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
```

Frontend repo: [clearbox_ai on GitHub](https://github.com/ethan-sam/clearbox_ai).