feat: initial HF Spaces deploy of NeuroScope backend

.dockerignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.pytest_cache/
+.mypy_cache/
+.venv/
+venv/
+env/
+.env
+.env.local
+.DS_Store
+*.swp
+.idea/
+.vscode/
+.git/
+.gitignore

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    TRANSFORMERS_CACHE=/app/.cache/huggingface \
+    HF_HOME=/app/.cache/huggingface
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY main.py model.py research.py ./
+
+RUN mkdir -p /app/.cache/huggingface && chmod -R 777 /app/.cache
+
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860", "--timeout-keep-alive", "120"]

README.md

@@ -1,12 +1,46 @@
 ---
-title: Neuroscope Api
-emoji: 🐢
-colorFrom: green
-colorTo: indigo
+title: NeuroScope API
+emoji: 🧠
+colorFrom: blue
+colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
-license: mit
-short_description: 'Browser-native mechanistic interpretability backend '
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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) for the NeuroScope frontend.
+
+## Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /load` | Load a HuggingFace model (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 /pca-trajectories` | 3D PCA of residual stream across layers + tokens |
+| `GET /contrastive-pairs` | Built-in sentiment contrastive prompt pairs |
+
+Interactive docs at `/docs` once the Space is live.
+
+## Configuration
+
+Set the following Space Variable/Secret in **Settings → Variables and secrets**:
+
+- `ALLOWED_ORIGINS` — comma-separated CORS origins (e.g. `https://neuroscope.vercel.app,http://localhost:3001`)
+
+## 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).

main.py

@@ -0,0 +1,264 @@
+"""
+NeuroScope-Web API Server
+
+FastAPI endpoints that expose Moon's research functions to the React frontend.
+This replaces the browser-based transformers.js worker with server-side
+TransformerLens inference.
+
+Run with: uvicorn main:app --reload --port 8000
+API docs: http://localhost:8000/docs
+"""
+
+import os
+from typing import List, Optional
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+import model
+import research
+
+# -----------------------------------------------------------------------------
+# App Setup
+# -----------------------------------------------------------------------------
+
+app = FastAPI(
+    title="NeuroScope-Web API",
+    description="Moon's interpretability research powered by TransformerLens",
+    version="0.1.0",
+)
+
+# CORS origins are configurable so the same image runs locally and on HF Spaces.
+# In production, set ALLOWED_ORIGINS to your deployed frontend URL(s), e.g.
+#   ALLOWED_ORIGINS=https://neuroscope.vercel.app,https://preview.neuroscope.vercel.app
+_default_origins = "http://localhost:3000,http://localhost:3001"
+ALLOWED_ORIGINS = [
+    origin.strip()
+    for origin in os.environ.get("ALLOWED_ORIGINS", _default_origins).split(",")
+    if origin.strip()
+]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# -----------------------------------------------------------------------------
+# Request/Response Models
+# -----------------------------------------------------------------------------
+# Pydantic models define the shape of data going in and out of endpoints
+
+class LoadRequest(BaseModel):
+    model_name: str = Field(default="gpt2-small", description="Model to load")
+
+
+class PromptRequest(BaseModel):
+    prompt: str = Field(..., description="Input text to analyze")
+
+
+class GradientRequest(BaseModel):
+    prompt: str
+    target_token: str = Field(..., description="Token to compute gradients toward")
+
+
+class AttentionRequest(BaseModel):
+    prompt: str
+    layer: int = Field(ge=0, le=11, description="Layer index (0-11 for GPT-2)")
+    head: int = Field(ge=0, le=11, description="Head index (0-11 for GPT-2)")
+
+
+class SteeringRequest(BaseModel):
+    positive_prompts: List[str] = Field(..., min_length=1)
+    negative_prompts: List[str] = Field(..., min_length=1)
+    layer: int = Field(default=6, ge=0, le=11, description="Layer for extraction")
+
+
+class SteeredGenerationRequest(BaseModel):
+    prompt: str
+    steering_vector: List[float]
+    alpha: float = Field(default=1.0, description="Steering strength")
+    layer: int = Field(default=6, ge=0, le=11)
+    max_new_tokens: int = Field(default=30, ge=1, le=100)
+
+
+class AblationRequest(BaseModel):
+    prompt: str
+    direction: List[float] = Field(
+        ..., description="Direction to project out of the residual stream"
+    )
+    layer: int = Field(default=6, ge=0, le=11, description="Layer for ablation")
+    max_new_tokens: int = Field(default=30, ge=1, le=100)
+
+
+# -----------------------------------------------------------------------------
+# Endpoints
+# -----------------------------------------------------------------------------
+
+@app.get("/")
+async def health():
+    """Simple health check - useful for verifying the server is running."""
+    return {"status": "ok", "service": "neuroscope-api"}
+
+
+@app.post("/load")
+async def load_model(req: LoadRequest):
+    """
+    Load a model into memory. Must be called before other endpoints.
+
+    GPT-2 small (~500MB) takes a few seconds to load on first call.
+    Subsequent calls with the same model return immediately.
+    """
+    try:
+        result = model.load_model(req.model_name)
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/logit-lens")
+async def logit_lens(req: PromptRequest):
+    """
+    Run logit lens analysis on a prompt.
+
+    Shows what the model would predict if we stopped at each layer.
+    This reveals how predictions refine through the network.
+
+    Moon's Eiffel Tower example: layers 0-10 predict "the",
+    layer 11 finally predicts "Paris".
+    """
+    try:
+        return research.logit_lens(req.prompt)
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.post("/attention")
+async def attention_pattern(req: AttentionRequest):
+    """
+    Get attention weights for a specific layer and head.
+
+    Returns a matrix showing how each token attends to others.
+    Useful for finding interesting attention patterns like:
+    - Previous token heads (copying behavior)
+    - Position heads (attending to specific positions)
+    - Induction heads (in-context learning)
+    """
+    try:
+        return research.get_attention_pattern(req.prompt, req.layer, req.head)
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.post("/gradients")
+async def token_gradients(req: GradientRequest):
+    """
+    Compute gradient-based token importance.
+
+    Shows which input tokens most influence the target prediction.
+    High gradient norm = modifying this token has big effect.
+
+    This is the foundation for adversarial attacks:
+    to change "Paris" → "Rome", focus on high-gradient tokens.
+    """
+    try:
+        return research.compute_token_gradients(req.prompt, req.target_token)
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.post("/steering-vector")
+async def steering_vector(req: SteeringRequest):
+    """
+    Compute a steering vector from contrastive prompts.
+
+    The vector points from negative → positive in activation space.
+    Add it during generation to steer toward positive sentiment.
+    Subtract it to steer toward negative sentiment.
+
+    Moon's default: use layer 6, which balances semantic content
+    with malleability.
+    """
+    try:
+        return research.extract_steering_vector(
+            req.positive_prompts,
+            req.negative_prompts,
+            req.layer,
+        )
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.get("/contrastive-pairs")
+async def contrastive_pairs():
+    """
+    Get Moon's curated sentiment pairs.
+
+    These are validated to tokenize to the same length,
+    which is required for computing steering vectors.
+    """
+    pairs = research.get_contrastive_pairs()
+    return {
+        "pairs": [{"positive": p, "negative": n} for p, n in pairs],
+        "count": len(pairs),
+    }
+
+
+@app.post("/generate-steered")
+async def generate_steered(req: SteeredGenerationRequest):
+    """
+    Generate text with a steering vector injected at a specific layer.
+    Returns both steered and baseline outputs for comparison.
+    """
+    try:
+        return research.generate_steered(
+            req.prompt,
+            req.steering_vector,
+            req.alpha,
+            req.layer,
+            req.max_new_tokens,
+        )
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.post("/ablate-direction")
+async def ablate_direction(req: AblationRequest):
+    """
+    Generate text with a direction projected out of the residual stream.
+
+    Implements h' = h - (h · d̂) d̂ at the chosen layer. This is the causal
+    counterpart to /generate-steered: where steering ADDS a scaled vector,
+    ablation REMOVES the component along the direction. Standard primitive
+    for testing claims like "direction d mediates behavior X" (Arditi et al.).
+
+    Returns ablated and baseline generations for side-by-side comparison.
+    """
+    try:
+        return research.ablate_along_direction(
+            req.prompt,
+            req.direction,
+            req.layer,
+            req.max_new_tokens,
+        )
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.post("/pca-trajectories")
+async def pca_trajectories(req: PromptRequest):
+    """
+    Get 3D PCA coordinates for all tokens across all layers.
+
+    This powers Moon's interactive 3D visualization showing
+    how token representations evolve through the network.
+
+    Returns x, y, z coordinates for each (token, layer) pair,
+    ready for Plotly or Three.js rendering on the frontend.
+    """
+    try:
+        return research.compute_pca_trajectories(req.prompt)
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))

model.py

@@ -0,0 +1,92 @@
+"""
+Model Manager - TransformerLens wrapper
+
+Provides a singleton HookedTransformer instance for the backend.
+This replaces Moon's manual HuggingFace setup with cleaner abstractions.
+"""
+
+from typing import Optional, Dict, Any
+import torch
+from transformer_lens import HookedTransformer
+
+# Global model instance (avoids reloading ~500MB on each request)
+_model: Optional[HookedTransformer] = None
+_model_name: Optional[str] = None
+
+
+def get_device() -> str:
+    """Detect best available device."""
+    if torch.cuda.is_available():
+        return "cuda"
+    elif torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+def load_model(name: str = "gpt2-small") -> Dict[str, Any]:
+    """
+    Load a HookedTransformer model.
+
+    Moon's notebooks used:
+        model = GPT2LMHeadModel.from_pretrained("gpt2")
+        model.config.output_attentions = True
+
+    TransformerLens equivalent:
+        model = HookedTransformer.from_pretrained("gpt2-small")
+        # Attentions and hidden states captured automatically via run_with_cache()
+    """
+    global _model, _model_name
+
+    if _model is not None and _model_name == name:
+        return {
+            "status": "already_loaded",
+            "model_name": name,
+            "n_layers": _model.cfg.n_layers,
+            "d_model": _model.cfg.d_model,
+        }
+
+    device = get_device()
+    _model = HookedTransformer.from_pretrained(name, device=device)
+    _model_name = name
+
+    return {
+        "status": "loaded",
+        "model_name": name,
+        "device": device,
+        "n_layers": _model.cfg.n_layers,
+        "d_model": _model.cfg.d_model,
+        "n_heads": _model.cfg.n_heads,
+        "d_vocab": _model.cfg.d_vocab,
+    }
+
+
+def get_model() -> HookedTransformer:
+    """Get loaded model, raise if none."""
+    if _model is None:
+        raise RuntimeError("No model loaded. Call load_model() first.")
+    return _model
+
+
+def run_with_cache(prompt: str):
+    """
+    Run inference and capture all activations.
+
+    Moon's notebooks did this manually:
+        outputs = model(**inputs, output_hidden_states=True)
+        hidden_states = outputs.hidden_states
+        attentions = outputs.attentions
+
+    TransformerLens:
+        logits, cache = model.run_with_cache(prompt)
+        # cache["blocks.0.hook_resid_post"] = residual after layer 0
+        # cache["blocks.0.attn.hook_pattern"] = attention pattern layer 0
+
+    Returns:
+        tokens: list of string tokens
+        logits: output logits tensor
+        cache: ActivationCache with all intermediate activations
+    """
+    model = get_model()
+    tokens = model.to_str_tokens(prompt)
+    logits, cache = model.run_with_cache(prompt)
+    return tokens, logits, cache

requirements.txt

@@ -0,0 +1,15 @@
+# NeuroScope-Web Backend
+# TransformerLens-powered interpretability engine
+
+# Core ML
+torch==2.3.0
+transformer-lens==2.11.0
+
+# API
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+pydantic==2.9.2
+
+# Analysis
+numpy==1.26.4
+scikit-learn==1.5.2

research.py

@@ -0,0 +1,470 @@
+"""
+Research Functions - Moon's interpretability logic powered by TransformerLens
+
+This module contains the core research functions from Moon's notebooks,
+adapted to use TransformerLens's cleaner cache API instead of manual hooks.
+
+The research questions and analysis logic are Moon's - we just swapped
+the plumbing from raw HuggingFace to TransformerLens.
+"""
+
+from typing import List, Dict, Any, Tuple
+import torch
+import torch.nn.functional as F
+from sklearn.decomposition import PCA
+
+from model import get_model, run_with_cache
+
+
+# -----------------------------------------------------------------------------
+# Logit Lens
+# -----------------------------------------------------------------------------
+# Moon's original: manually grabbed hidden states, multiplied by lm_head.weight
+# TransformerLens: we use the cache and model.unembed() or direct W_U access
+
+def logit_lens(prompt: str, top_k: int = 5) -> Dict[str, Any]:
+    """
+    Apply the unembedding matrix to each layer's residual stream.
+
+    This answers: "If we stopped the model at layer L, what would it predict?"
+
+    The idea (from nostalgebraist's blog) is that each layer refines the
+    prediction. Early layers often predict generic tokens like "the",
+    while later layers converge on the contextually correct answer.
+
+    Moon's notebook showed this beautifully with the Eiffel Tower example:
+    layers 0-10 all predicted "the", but layer 11 finally predicted "Paris".
+
+    Math: logits_L = hidden_state_L @ W_U.T
+    where W_U is the unembedding matrix (vocab x hidden_dim)
+    """
+    model = get_model()
+    tokens, logits, cache = run_with_cache(prompt)
+
+    # W_U maps from hidden dimension to vocabulary
+    # In GPT-2, this is tied to the embedding matrix
+    W_U = model.W_U  # shape: [d_model, d_vocab]
+
+    layer_predictions = []
+
+    for layer_idx in range(model.cfg.n_layers + 1):
+        # Layer 0 is the embedding, layers 1-12 are transformer blocks
+        # TransformerLens uses "blocks.X.hook_resid_post" for post-layer residuals
+        if layer_idx == 0:
+            # Embedding layer - before any transformer blocks
+            resid = cache["hook_embed"] + cache["hook_pos_embed"]
+        else:
+            # After transformer block (layer_idx - 1)
+            resid = cache[f"blocks.{layer_idx - 1}.hook_resid_post"]
+
+        # We only care about the last token position (next token prediction)
+        last_token_resid = resid[0, -1, :]  # shape: [d_model]
+
+        # Project to vocabulary space
+        # Note: Moon's code skipped layer norm here for "raw" analysis
+        # For prediction parity with the model, you'd apply ln_final first
+        vocab_logits = last_token_resid @ W_U  # shape: [d_vocab]
+        probs = F.softmax(vocab_logits, dim=-1)
+
+        # Get top-k predictions
+        top_probs, top_indices = torch.topk(probs, top_k)
+        predictions = [
+            {"token": model.to_string(idx.item()), "prob": round(p.item(), 4)}
+            for p, idx in zip(top_probs, top_indices)
+        ]
+
+        layer_name = "Embed" if layer_idx == 0 else f"Layer {layer_idx - 1}"
+        layer_predictions.append({"layer": layer_name, "top_k": predictions})
+
+    return {"prompt": prompt, "tokens": tokens, "predictions": layer_predictions}
+
+
+# -----------------------------------------------------------------------------
+# Attention Patterns
+# -----------------------------------------------------------------------------
+# Moon's notebook visualized these as heatmaps to see what tokens attend to what
+
+def get_attention_pattern(prompt: str, layer: int, head: int) -> Dict[str, Any]:
+    """
+    Extract attention weights for a specific layer and head.
+
+    The attention pattern shows how each token "looks at" other tokens.
+    Shape is [seq_len, seq_len] where entry [i,j] is how much token i
+    attends to token j.
+
+    Moon used these to identify interesting heads - some heads attend to
+    the previous token (useful for copying), others attend to specific
+    syntactic positions.
+
+    GPT-2 small has 12 layers x 12 heads = 144 attention patterns to explore!
+    """
+    model = get_model()
+    tokens, logits, cache = run_with_cache(prompt)
+
+    # TransformerLens stores attention patterns at this hook point
+    # Shape: [batch, n_heads, seq_len, seq_len]
+    attn_pattern = cache[f"blocks.{layer}.attn.hook_pattern"]
+
+    # Extract the specific head we want
+    head_pattern = attn_pattern[0, head].cpu().tolist()  # [seq_len, seq_len]
+
+    return {
+        "prompt": prompt,
+        "tokens": tokens,
+        "layer": layer,
+        "head": head,
+        "pattern": head_pattern,
+    }
+
+
+# -----------------------------------------------------------------------------
+# Gradient Analysis (Token Susceptibility)
+# -----------------------------------------------------------------------------
+# This is Moon's "Foundation for Adversarial Attacks" section
+# It tells us which input tokens most influence a target prediction
+
+def compute_token_gradients(prompt: str, target_token: str) -> Dict[str, Any]:
+    """
+    Compute how much each input token influences the target prediction.
+
+    Moon's insight: if you want to steer the model from predicting "Paris"
+    to predicting "Rome", which input tokens should you modify?
+
+    The gradient norm tells us the "susceptibility" of each position.
+    High gradient norm = changing this token has big impact on the target.
+
+    Moon's example showed that "iff" (from Eiffel), "city", and "Tower"
+    had the highest gradients when trying to change the prediction to Rome.
+    This makes intuitive sense - these are the most "French" tokens.
+
+    Math: We compute d(loss)/d(embedding) where loss = -log P(target)
+    """
+    model = get_model()
+
+    # Tokenize
+    tokens_tensor = model.to_tokens(prompt)  # [1, seq_len]
+    str_tokens = model.to_str_tokens(prompt)
+    target_id = model.to_single_token(target_token)
+
+    # Get embeddings with gradient tracking
+    # We need to manually build the forward pass to get gradients on embeddings
+    embed = model.embed(tokens_tensor)  # [1, seq_len, d_model]
+    pos_embed = model.pos_embed(tokens_tensor)
+
+    # Combine and enable gradients
+    # We keep a reference to this tensor since we want gradients w.r.t. it
+    input_resid = (embed + pos_embed).detach().requires_grad_(True)
+
+    # Forward through transformer blocks
+    resid = input_resid
+    for block in model.blocks:
+        resid = block(resid)
+
+    # Final layer norm and unembedding
+    resid = model.ln_final(resid)
+    logits = resid @ model.W_U  # [1, seq_len, d_vocab]
+
+    # Loss: negative log probability of target token at last position
+    last_logits = logits[0, -1, :]
+    log_probs = F.log_softmax(last_logits, dim=-1)
+    loss = -log_probs[target_id]
+
+    # Backpropagate
+    loss.backward()
+
+    # The gradient on input_resid tells us sensitivity per position
+    # We take the L2 norm across the hidden dimension
+    grad_norms = input_resid.grad[0].norm(dim=-1).tolist()  # [seq_len]
+
+    # Normalize for easier interpretation (0 to 1 scale)
+    max_norm = max(grad_norms)
+    normalized = [g / max_norm if max_norm > 0 else 0 for g in grad_norms]
+
+    return {
+        "prompt": prompt,
+        "target_token": target_token,
+        "tokens": str_tokens,
+        "gradient_norms": [
+            {"token": t, "norm": round(g, 4), "normalized": round(n, 4)}
+            for t, g, n in zip(str_tokens, grad_norms, normalized)
+        ],
+    }
+
+
+# -----------------------------------------------------------------------------
+# Steering Vectors
+# -----------------------------------------------------------------------------
+# Moon's steering_vectors.ipynb - the core of activation engineering
+
+def get_contrastive_pairs() -> List[Tuple[str, str]]:
+    """
+    Moon's curated contrastive pairs for sentiment steering.
+
+    These pairs are designed so that:
+    1. They differ only in sentiment (positive vs negative)
+    2. They tokenize to the same length (critical for subtraction!)
+
+    Moon validated each pair's token length in the notebook.
+    """
+    return [
+        ("I think this movie is amazing", "I think this movie is terrible"),
+        ("The food at this restaurant is delicious", "The food at this restaurant is disgusting"),
+        ("I am feeling very happy today", "I am feeling very sad today"),
+        ("The product quality is excellent", "The product quality is awful"),
+        ("My experience was wonderful", "My experience was horrible"),
+        ("He is a very kind person", "He is a very mean person"),
+        ("The weather is beautiful", "The weather is nasty"),
+        ("This solution is perfect", "This solution is useless"),
+    ]
+
+
+def extract_steering_vector(
+    positive_prompts: List[str],
+    negative_prompts: List[str],
+    layer: int,
+) -> Dict[str, Any]:
+    """
+    Compute a steering vector from contrastive examples.
+
+    Moon's formula: v_steering = mean(h_positive) - mean(h_negative)
+
+    This vector points in the direction of "positiveness" in activation space.
+    Adding it during generation steers toward positive sentiment.
+    Subtracting it steers toward negative sentiment.
+
+    We extract from the last token position because GPT-2 aggregates
+    context causally - the last token "knows" the full sequence.
+
+    Layer choice matters:
+    - Early layers (0-3): Low-level features, less semantic
+    - Middle layers (4-8): Good for semantic steering
+    - Late layers (9-11): Close to output, can be unstable
+    Moon typically used layer 6 as a good default.
+    """
+    model = get_model()
+
+    def get_last_token_activation(prompt: str, layer_idx: int) -> torch.Tensor:
+        """Extract residual stream at layer for the last token."""
+        _, _, cache = run_with_cache(prompt)
+        resid = cache[f"blocks.{layer_idx}.hook_resid_post"]
+        return resid[0, -1, :]  # [d_model]
+
+    # Collect activations for both sets
+    pos_activations = [get_last_token_activation(p, layer) for p in positive_prompts]
+    neg_activations = [get_last_token_activation(n, layer) for n in negative_prompts]
+
+    # Compute means
+    mean_pos = torch.stack(pos_activations).mean(dim=0)
+    mean_neg = torch.stack(neg_activations).mean(dim=0)
+
+    # Steering vector: direction from negative to positive
+    steering_vector = mean_pos - mean_neg
+
+    return {
+        "layer": layer,
+        "n_positive": len(positive_prompts),
+        "n_negative": len(negative_prompts),
+        "vector_norm": round(steering_vector.norm().item(), 4),
+        "vector": steering_vector.tolist(),
+    }
+
+
+# -----------------------------------------------------------------------------
+# PCA Trajectories
+# -----------------------------------------------------------------------------
+# Moon's 3D visualization of how token representations evolve through layers
+
+def compute_pca_trajectories(prompt: str) -> Dict[str, Any]:
+    """
+    Project all token representations through layers into 3D space.
+
+    Moon's insight: tokens start at similar positions (embeddings) and
+    diverge as they pass through layers. The trajectories reveal how
+    the model processes different tokens.
+
+    Questions this helps answer:
+    - Do semantically related tokens stay close? (e.g., "Eiffel" and "Tower")
+    - Where do trajectories diverge? Which layer differentiates roles?
+    - Do function words (the, is) behave differently from content words?
+
+    Moon noted that PC1 often captures ~97% of variance, suggesting
+    the residual stream has a dominant direction (likely related to
+    predicting the next token).
+    """
+    model = get_model()
+    tokens, logits, cache = run_with_cache(prompt)
+
+    # Collect all representations: every token at every layer
+    all_vectors = []
+    metadata = []
+
+    for layer_idx in range(model.cfg.n_layers + 1):
+        if layer_idx == 0:
+            resid = cache["hook_embed"] + cache["hook_pos_embed"]
+        else:
+            resid = cache[f"blocks.{layer_idx - 1}.hook_resid_post"]
+
+        for token_idx, token_str in enumerate(tokens):
+            vec = resid[0, token_idx, :].cpu().numpy()
+            all_vectors.append(vec)
+            metadata.append({
+                "token": token_str,
+                "token_idx": token_idx,
+                "layer": layer_idx,
+            })
+
+    # Fit PCA on all vectors together (unified coordinate space)
+    import numpy as np
+    vectors_matrix = np.stack(all_vectors)
+    pca = PCA(n_components=3)
+    coords_3d = pca.fit_transform(vectors_matrix)
+
+    # Attach coordinates to metadata
+    results = []
+    for i, meta in enumerate(metadata):
+        results.append({
+            **meta,
+            "x": round(float(coords_3d[i, 0]), 4),
+            "y": round(float(coords_3d[i, 1]), 4),
+            "z": round(float(coords_3d[i, 2]), 4),
+        })
+
+    return {
+        "prompt": prompt,
+        "tokens": tokens,
+        "variance_explained": [round(v, 4) for v in pca.explained_variance_ratio_],
+        "trajectories": results,
+    }
+
+
+# -----------------------------------------------------------------------------
+# Steered Generation
+# -----------------------------------------------------------------------------
+
+def generate_steered(
+    prompt: str,
+    steering_vector: List[float],
+    alpha: float,
+    layer: int,
+    max_new_tokens: int = 30,
+) -> Dict[str, Any]:
+    """
+    Generate text with a steering vector injected at the specified layer.
+
+    The steering vector is added to the residual stream during the forward pass:
+      h_steered = h_original + alpha * v_steering
+
+    Positive alpha steers toward the positive direction (e.g., positive sentiment).
+    Negative alpha steers toward the negative direction.
+    """
+    model = get_model()
+
+    tokens = model.to_tokens(prompt)
+
+    steering_tensor = torch.tensor(steering_vector, dtype=torch.float32, device=model.cfg.device)
+
+    def steering_hook(activation, hook):
+        # activation shape: [batch, seq_len, d_model]
+        # Add the steering vector (scaled by alpha) to all token positions
+        activation[:, :, :] = activation[:, :, :] + alpha * steering_tensor
+        return activation
+
+    # Generate with the hook active at the specified layer
+    hook_name = f"blocks.{layer}.hook_resid_post"
+
+    with model.hooks(fwd_hooks=[(hook_name, steering_hook)]):
+        output = model.generate(
+            tokens,
+            max_new_tokens=max_new_tokens,
+            temperature=0.7,
+            do_sample=True,
+        )
+
+    generated_text = model.to_string(output[0])
+
+    # Also generate without steering for comparison
+    baseline_output = model.generate(
+        tokens,
+        max_new_tokens=max_new_tokens,
+        temperature=0.7,
+        do_sample=True,
+    )
+    baseline_text = model.to_string(baseline_output[0])
+
+    return {
+        "prompt": prompt,
+        "layer": layer,
+        "alpha": alpha,
+        "steered_text": generated_text,
+        "baseline_text": baseline_text,
+    }
+
+
+# -----------------------------------------------------------------------------
+# Direction Ablation (Projection Removal)
+# -----------------------------------------------------------------------------
+# The causal counterpart to steering: instead of ADDING a vector, REMOVE the
+# component of the residual stream that lies along the direction. This is the
+# standard primitive for testing causal claims of the form "direction d
+# mediates behavior X" (Arditi et al., 2024 — refusal direction).
+
+def ablate_along_direction(
+    prompt: str,
+    direction: List[float],
+    layer: int,
+    max_new_tokens: int = 30,
+) -> Dict[str, Any]:
+    """
+    Generate text with the projection along `direction` removed at `layer`.
+
+    Hook math: h' = h - (h · d̂) d̂   where d̂ = direction / ||direction||
+
+    Zeros the residual stream's component along d̂ at every token position of
+    the chosen layer. Contrast with generate_steered, which adds alpha * v.
+
+    Returns both ablated and baseline generations so the caller can show a
+    side-by-side. Sampling temperature matches generate_steered for parity.
+    """
+    model = get_model()
+
+    direction_tensor = torch.tensor(
+        direction, dtype=torch.float32, device=model.cfg.device
+    )
+    norm = direction_tensor.norm()
+    if norm.item() < 1e-8:
+        raise RuntimeError("direction has near-zero norm; cannot ablate")
+    unit_direction = direction_tensor / norm
+
+    tokens = model.to_tokens(prompt)
+
+    def ablation_hook(activation, hook):
+        # activation shape: [batch, seq_len, d_model]
+        # Project each position's residual onto d̂, subtract that component.
+        coeffs = (activation * unit_direction).sum(dim=-1, keepdim=True)
+        activation[:, :, :] = activation - coeffs * unit_direction
+        return activation
+
+    hook_name = f"blocks.{layer}.hook_resid_post"
+
+    with model.hooks(fwd_hooks=[(hook_name, ablation_hook)]):
+        ablated_output = model.generate(
+            tokens,
+            max_new_tokens=max_new_tokens,
+            temperature=0.7,
+            do_sample=True,
+        )
+
+    baseline_output = model.generate(
+        tokens,
+        max_new_tokens=max_new_tokens,
+        temperature=0.7,
+        do_sample=True,
+    )
+
+    return {
+        "prompt": prompt,
+        "layer": layer,
+        "direction_norm_before": round(float(norm.item()), 4),
+        "ablated_text": model.to_string(ablated_output[0]),
+        "baseline_text": model.to_string(baseline_output[0]),
+    }