Wire fine-tuned interpreter analysis

AGENTS.md

@@ -0,0 +1,177 @@
+# DOX framework
+
+- DOX is highly performant AGENTS.md hierarchy installed here
+- Agent must follow DOX instructions across any edits
+
+## Core Contract
+
+- AGENTS.md files are binding work contracts for their subtrees
+- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it
+
+## Read Before Editing
+
+1. Read the root AGENTS.md
+2. Identify every file or folder you expect to touch
+3. Walk from the repository root to each target path
+4. Read every AGENTS.md found along each route
+5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
+6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
+7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX
+
+Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.
+
+## Update After Editing
+
+Every meaningful change requires a DOX pass before the task is done.
+
+Update the closest owning AGENTS.md when a change affects:
+
+- purpose, scope, ownership, or responsibilities
+- durable structure, contracts, workflows, or operating rules
+- required inputs, outputs, permissions, constraints, side effects, or artifacts
+- user preferences about behavior, communication, process, organization, or quality
+- AGENTS.md creation, deletion, move, rename, or index contents
+
+Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.
+
+## Hierarchy
+
+- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
+- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
+- Each parent explains what its direct children cover and what stays owned by the parent
+- The closer a doc is to the work, the more specific and practical it must be
+
+## Child Doc Shape
+
+- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
+- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
+- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists
+
+Default section order:
+- Purpose
+- Ownership
+- Local Contracts
+- Work Guidance
+- Verification
+- Child DOX Index
+
+## Style
+
+- Keep docs concise, current, and operational
+- Document stable contracts, not diary entries
+- Put broad rules in parent docs and concrete details in child docs
+- Prefer direct bullets with explicit names
+- Do not duplicate rules across many files unless each scope needs a local version
+- Delete stale notes instead of explaining history
+- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist
+
+## Closeout
+
+1. Re-check changed paths against the DOX chain
+2. Update nearest owning docs and any affected parents or children
+3. Refresh every affected Child DOX Index
+4. Remove stale or contradictory text
+5. Run existing verification when relevant
+6. Report any docs intentionally left unchanged and why
+
+## User Preferences
+
+When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md
+
+- User wants to be very ambitious for this hackathon
+- User wants to go deep on manifold research, not just surface-level framing
+- User prefers maximizing prize stacking across multiple categories
+
+---
+
+## Project: Build Small Hackathon (Gradio)
+
+### Purpose
+
+Gradio "Build Small" hackathon project. Build an ambitious HF Space powered by ≤32B models using Gradio, deployed under the hackathon org. Aiming for multiple prize categories.
+
+### Concept Direction (current — pivoted)
+
+**Activation Brain** — A live comparative interpretability visualizer: two Gemma streams drive dual EEGs, baseline-corrected emotion deltas, model-native meters, and a generated comparison analysis panel. The prior 3D brain view was replaced because a single brain was less clear once both models run simultaneously. The user picks between **two architecturally identical Gemma-4-12B models** — `google/gemma-4-12B-it` (base) and `OBLITERATUS/Gemma-4-12B-OBLITERATED` (abliterated/uncensored) — sharing ONE UMAP frame so firing differences are directly comparable (a censored-vs-uncensored interpretability demo).
+
+**Pivot history:** Started as "Activation Avatars" (Qwen3-4B hidden states → FLUX.2-Klein face + LivePortrait animation). Abandoned because per-token emotion mapping to a human face produced uncanny flicker (timescale/subspace mismatch — a face has affective inertia; fast multi-emotion change reads as noise). A brain/EEG is *expected* to fire fast across many regions simultaneously, so the pivot dissolved the core problem and deleted the fragile face stack (FLUX, LivePortrait, expression regressor).
+
+**Why two Gemmas (not Qwen):** Qwen3-4B (36 layers, 2560 dim) is not comparable to Gemma (48 layers, 3840 dim). The two Gemma-4-12B models ARE identical, enabling a valid same-space comparison. Measured signature: abliteration drops the deep-shell (layer 36) activation norm (153.06→146.21) while surface/mid layers are unchanged.
+- Goodfire AI's neural geometry research underpins the manifold approach (manifold steering, curved-manifold concepts, SAE limitations).
+
+### Hard Constraints
+
+- Model ≤ 32B parameters
+- Gradio app on HF Spaces under `build-small-hackathon` org
+- Deadline: June 15, 2026
+- Compute: $250 Modal credits + $20 HF credits + 40min/day ZeroGPU
+- Submission: Space + demo video + social post
+- Unlimited submissions allowed, max 10 ZeroGPU Spaces
+- Can submit to both tracks
+
+### Models
+
+- **google/gemma-4-12B-it** (base) — hidden-state source, 48 layers, 3840 dim, arch `gemma4_unified`, decoder hooks at layers 12/24/36, decoder path `model.language_model.layers`
+- **OBLITERATUS/Gemma-4-12B-OBLITERATED** (abliterated/uncensored) — architecturally identical twin; shares hooks/dims/tokenizer → valid same-space comparison
+- Both 12B (≤32B OK, but **Tiny Titan ≤4B forfeited** — traded for the censored-vs-uncensored interpretability demo)
+- No image model in the hot path (FLUX/LivePortrait removed in the brain pivot)
+
+### Prize Targeting Strategy
+
+| Target | Prize | Path |
+|---|---|---|
+| 🍄 Thousand Token Wood | $4,000 (1st) | Weird + delightful (live brain firing) |
+| Modal | $10,000 credits (1st) | Serve both Gemmas on Modal |
+| Community Choice | $2,000 | Viral/shareable |
+| Best Demo | $1,000 | Real-time neuron firing + EEG |
+| Judges' Wildcard | $1,000 | Censored-vs-uncensored interpretability art |
+| Bonus Quest Champion | $2,000 | badges on main project |
+| ~~BFL~~ | ~~$5,000~~ | forfeited (no FLUX in brain pivot) |
+| ~~Tiny Titan~~ | ~~$1,500~~ | forfeited (12B > 4B cap) |
+
+### Badge Strategy (per project, "single sash")
+
+Main project badge paths (brain pivot):
+- ✅ 🎨 Off-Brand — custom 3D-brain + EEG visualization UI (Three.js)
+- ✅ 📡 Sharing is Caring — publish per-model brain bundles + neuron clouds on Hub
+- ✅ 📓 Field Notes — blog post on manifold research + the abliteration deep-shell finding + the build
+- ✅ 🎯 Well-Tuned — fine-tuned `Ministral-8B-Instruct` LoRA interpreter published as `build-small-hackathon/activation-brain-interpreter`; it translates hidden-layer-derived telemetry into comparison analysis
+- ❌ 🦙 Llama Champion — dropped with Qwen (no 4B model in scope now)
+- ❌ 🔌 Off the Grid — conflicts with Modal ($10k prize); 12B is hard to run local anyway
+
+### Prior Art & Research
+
+- **Milady project** (`/a0/usr/projects/milady`): Activation Avatars — 3 trained adapter checkpoints (CrossAttention, MultiToken), ~2M params each. Maps Qwen3-4B layers 9/18/27 hidden states → FLUX.2-Klein prompt embeddings. 20 emotions. Results: milady-style face images per emotion.
+- **Goodfire research** (May-June 2026): Neural geometry series. Key papers:
+  - "The World Inside Neural Networks" — concepts on curved manifolds
+  - "Steering Along Manifolds" — manifold steering >> linear steering on Llama 3.1 8B
+  - "Geometric Calculator" — general-purpose addition module in layer 18 computing over circular geometry
+  - "Can SAEs Capture Neural Geometry?" — SAEs shatter/dilute manifold structure
+- **Hackathon winners research**: One-sentence pitch + instant wow, multi-agent clear roles, optimize experience not model, latency engineering wins, nail deliverables, community likes count
+
+### Architecture (deployed)
+### Public Technical Artifacts
+
+- HF Dataset `build-small-hackathon/activation-brain-artifacts` publishes the reproducibility bundle: Gemma fingerprint JSONs, 627 affect-labeled probe prompts, manifold plots, `manifold_processed.npz`, summary report, fingerprinting script, analysis scripts, Modal backend reference code, and interpreter training/serving scripts.
+- HF Model `build-small-hackathon/activation-brain-interpreter` publishes the fine-tuned Mistral-family LoRA interpreter adapter used for generated comparison analysis.
+- The raw local `manifold_data.pt` hidden-state dump remains unpublished intentionally; use processed/public artifacts for submission evidence unless raw activations are explicitly requested.
+
+
+- **Modal** `gemma-brain` app — two classes `BaseGemma` + `OblitGemma` (L40S), each loads its model + precomputed brain bundle, streams `fire`/`token`/`done` SSE. Hook path `model.language_model.layers`, hooks [12,24,36].
+- **Interpreter** `activation-brain-interpreter` Modal app — serves the published `build-small-hackathon/activation-brain-interpreter` LoRA adapter on `mistralai/Ministral-8B-Instruct-2410`; `/api/analyze` proxies prompt + both responses + baseline-corrected deltas + native meters to generate varied plain-English analysis. Deterministic frontend analysis remains fallback.
+- **Frontend** `brain_app.py` (Gradio + FastAPI) — per-model same-origin proxy routes `/api/{neurons,init,stream}/{model}` plus `/api/analyze`, serves `static/brain_engine.js` (dual EEG + comparison analysis UI). **Dual concurrent mode (no dropdown):** one Send opens TWO parallel SSE streams (base + oblit); each drives its own EEG strip (right column), both model responses are shown labeled in chat, and the left column shows a live plain-English comparison-analysis card beneath Stats instead of the older single 3D brain; the analysis emphasizes what the divergence means for tone, warmth, caution, uncertainty, and shared-manifold trajectory rather than only listing metric values. Each EEG includes baseline-corrected emotion activation deltas (positive excess over the first 8 fire events of that response, not argmax counts) plus a calibrated baseline-corrected model-native state meter derived from live weights: uniform 0–100 Valence, Activation, Uncertainty, Constraint, activity-gated Conflict, and Warmth. `mdLite()` renders safe markdown + collapses degenerate loops.
+- **Fingerprints** built by `fingerprint_model.py` (model-agnostic; shared UMAP fit on base, transform on oblit) → `gemma4_{base,oblit}_{neurons.json,brain_bundle.pt}` on Modal volume `avatars-cache`.
+- Note: Gradio mounts `gr.HTML` asynchronously, so `brain_engine.js` must poll for `#ab-brain` before init (boot poller) — otherwise the canvas stays blank.
+
+### Key Documents
+
+- `BRIEFING.md` — Full hackathon rules, prizes, timeline, strategy, badges, sponsor model catalog, winning playbook
+- Tracker at `/a0/usr/workdir/office-manager/tracker.json`
+
+### Decision Log
+
+Tracked in `BRIEFING.md` section 11.
+
+## Child DOX Index
+
+No child directories yet. Will be created as project grows (e.g., `src/`, `adapters/`, `notebooks/`).