Initial commit

.gitignore

@@ -0,0 +1,10 @@
+default_weights/
+*.pt
+*.pth
+*.bin
+__pycache__/
+*.pyc
+.streamlit/
+*.log
+.DS_Store
+temp_sae/

CODING_STYLE.md

@@ -0,0 +1,52 @@
+# Coding Style Guide
+
+## Emoji Usage Policy
+
+### Rule: No Emojis in Backend Code
+
+Emojis should ONLY be used for frontend/web display purposes.
+
+### Allowed:
+- Streamlit UI elements (st.header, st.markdown, st.info, etc.)
+- HTML content displayed to users
+- Web page titles and headers
+
+### NOT Allowed:
+- Python print() statements
+- Log messages
+- Error messages in backend
+- Comments in code
+- Documentation files (README.md, etc.)
+- Shell scripts
+- Command-line output
+
+### Examples:
+
+#### Correct (Frontend Display):
+```python
+st.header("Configuration")
+st.info("Current Task: **Toxicity Detection**")
+st.success("Loaded from repository")
+```
+
+#### Incorrect (Backend Logic):
+```python
+print("Created repository: {repo}")
+print("Uploaded SAE weights to {repo}")
+logger.info("Processing complete")
+```
+
+### Rationale:
+1. Backend code should be clean and professional
+2. Emojis can cause encoding issues in terminals
+3. Better compatibility across different systems
+4. More suitable for logs and debugging
+5. Easier to parse programmatically
+
+### Verification:
+All non-UI Python files, shell scripts, and documentation files have been cleaned of emojis.
+Only app.py contains emojis, exclusively for Streamlit web display.
+
+---
+
+Last updated: 2026-01-31

README.md

@@ -0,0 +1,140 @@
+# FAC-Synthesis Demo
+
+Interactive demo for "Less is Enough: Synthesizing Diverse Data in Feature Space of LLMs"
+
+## Quick Start
+
+### Local Testing
+
+```bash
+cd demo
+pip install -r requirements.txt
+streamlit run app.py
+```
+
+Open http://localhost:8501 in your browser.
+
+## Deploy to Public (Recommended: Streamlit Cloud)
+
+### Step 1: Push to GitHub
+
+```bash
+cd demo
+git init
+git add .
+git commit -m "Initial commit"
+git remote add origin https://github.com/YOUR_USERNAME/fac-synthesis-demo.git
+git branch -M main
+git push -u origin main
+```
+
+### Step 2: Deploy on Streamlit Cloud
+
+1. Go to https://share.streamlit.io
+2. Sign in with your GitHub account (free)
+3. Click "New app"
+4. Select your repository: `YOUR_USERNAME/fac-synthesis-demo`
+5. Set main file path: `app.py`
+6. Click "Deploy"
+
+Done! Your app will be live at: `https://YOUR-USERNAME-fac-synthesis-demo.streamlit.app`
+
+### Why Streamlit Cloud?
+
+- Completely free
+- 5-minute setup
+- Auto-deploy on git push
+- Built-in HTTPS
+- No server management
+
+## Features
+
+### SAE Configuration
+- Load SAE weights from default path, Hugging Face, or upload files
+- Adjust activation threshold (0.0 to 4.0)
+- Support for LLaMA, Mistral, Qwen models
+
+### Data Synthesizer
+- Choose from LLaMA-3.1-8B, Mistral-7B, Qwen2-7B
+- Optional GPT-4o-mini (no GPU required, API key needed)
+
+### Core Functions
+- Feature Analysis: Analyze text and visualize SAE activations
+- Targeted Synthesis: Generate text that activates specific features
+- FAC Coverage: Compute coverage metrics for datasets
+- Batch Synthesis: Generate multiple samples efficiently
+
+### Advanced
+- Load custom datasets from Hugging Face
+- Use your own SAE checkpoints
+- Extend to new tasks
+
+## Configuration
+
+### GPU Requirements
+- Local models (LLaMA/Mistral/Qwen): 16GB+ VRAM recommended
+- GPT-4o-mini: No GPU needed (cloud API)
+
+### SAE Weight Options
+
+**Option 1: Default (Local)**
+Place weights in:
+```
+demo/default_weights/Llama-3.1-8B-Instruct/sae_l16.pt
+```
+
+**Option 2: Hugging Face (Recommended)**
+In the app:
+1. Select "Hugging Face" as source
+2. Enter repository ID: `username/sae-weights`
+3. Enter filename: `sae_l16.pt`
+4. Click "Load"
+
+**Option 3: Upload**
+Upload `.pt` or `.pth` files directly (max 200MB)
+
+## Troubleshooting
+
+**CUDA Out of Memory**
+- Switch to GPT-4o-mini synthesizer
+- Use smaller model (Mistral-7B)
+- Close other GPU applications
+
+**SAE Weights Not Found**
+- Use Hugging Face option
+- Check file path in `default_weights/`
+
+**Import Errors**
+```bash
+pip install -r requirements.txt --upgrade
+```
+
+## Upload Your SAE to Hugging Face
+
+```python
+from huggingface_hub import HfApi
+
+api = HfApi()
+api.upload_file(
+    path_or_fileobj="path/to/sae_l16.pt",
+    path_in_repo="sae_l16.pt",
+    repo_id="your-username/sae-weights",
+    repo_type="model"
+)
+```
+
+See `upload_to_hf_example.py` for more details.
+
+## Citation
+
+```bibtex
+@article{less-is-enough-2026,
+  title={Less is Enough: Synthesizing Diverse Data in Feature Space of LLMs},
+  author={...},
+  year={2026}
+}
+```
+
+## License
+
+MIT License

app.py

@@ -0,0 +1,571 @@
+import streamlit as st
+import torch
+import numpy as np
+from pathlib import Path
+import json
+import sys
+import os
+from huggingface_hub import hf_hub_download, snapshot_download
+from datasets import load_dataset
+import openai
+
+try:
+    sys.path.append(str(Path(__file__).parent.parent / "FAC-Synthesis"))
+    from utils.model_loader import load_model_and_sae, get_available_models
+    from utils.feature_analyzer import FeatureAnalyzer
+    from utils.synthesis_engine import SynthesisEngine
+    from utils.visualization import plot_activation_heatmap, highlight_text_spans
+    from utils.feature_db import FeatureDatabase
+except Exception as e:
+    st.error(f"Import error: {e}")
+    st.stop()
+
+st.set_page_config(
+    page_title="FAC-Synthesis Demo",
+    page_icon="✨",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+st.markdown("""
+<style>
+    .main-header {
+        font-size: 2.5rem;
+        font-weight: 800;
+        text-align: center;
+        margin-bottom: 0.5rem;
+        color: #1e293b;
+    }
+    .sub-header {
+        font-size: 1.2rem;
+        text-align: center;
+        color: #64748b;
+        margin-bottom: 2rem;
+    }
+    .metric-card {
+        background: #f8fafc;
+        padding: 1.5rem;
+        border-radius: 8px;
+        border: 1px solid #e2e8f0;
+    }
+    .success-box {
+        background: #dcfce7;
+        padding: 1rem;
+        border-radius: 6px;
+        border-left: 4px solid #22c55e;
+    }
+    .warning-box {
+        background: #fef3c7;
+        padding: 1rem;
+        border-radius: 6px;
+        border-left: 4px solid #f59e0b;
+    }
+    .error-box {
+        background: #fee2e2;
+        padding: 1rem;
+        border-radius: 6px;
+        border-left: 4px solid #ef4444;
+    }
+</style>
+""", unsafe_allow_html=True)
+
+@st.cache_resource
+def initialize_feature_db():
+    try:
+        return FeatureDatabase()
+    except Exception as e:
+        st.error(f"Error loading feature database: {e}")
+        return None
+
+@st.cache_resource
+def load_models(model_name, sae_path, threshold):
+    try:
+        return load_model_and_sae(model_name, sae_path, threshold)
+    except Exception as e:
+        st.error(f"Error loading models: {e}")
+        return None, None, None
+
+@st.cache_resource
+def load_sae_from_hf(repo_id, filename):
+    try:
+        with st.spinner(f"Downloading SAE weights from {repo_id}..."):
+            sae_path = hf_hub_download(repo_id=repo_id, filename=filename)
+        return sae_path
+    except Exception as e:
+        st.error(f"Error downloading SAE from Hugging Face: {e}")
+        return None
+
+@st.cache_resource
+def load_dataset_from_hf(repo_id):
+    try:
+        with st.spinner(f"Loading dataset from {repo_id}..."):
+            dataset = load_dataset(repo_id)
+        return dataset
+    except Exception as e:
+        st.error(f"Error loading dataset from Hugging Face: {e}")
+        return None
+
+def generate_with_gpt4o(prompt, api_key):
+    try:
+        openai.api_key = api_key
+        response = openai.ChatCompletion.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0.7
+        )
+        return response.choices[0].message.content
+    except Exception as e:
+        st.error(f"GPT-4o-mini API error: {e}")
+        return None
+
+def main():
+    st.markdown('<div class="main-header">✨ FAC-Synthesis Demo</div>', unsafe_allow_html=True)
+    st.markdown('<div class="sub-header">Less is Enough: Feature-Guided Data Synthesis</div>', unsafe_allow_html=True)
+    
+    with st.sidebar:
+        task_type = "Toxicity Detection"
+        task_key = "toxicity"
+        
+        synthesizer_mapping = {
+            "LLaMA-3.1-8B-Instruct": "meta-llama/Llama-3.1-8B-Instruct",
+            "Mistral-7B-Instruct": "mistralai/Mistral-7B-Instruct-v0.2",
+            "Qwen2-7B-Instruct": "Qwen/Qwen2-7B-Instruct",
+            "GPT-4o-mini (API)": "gpt-4o-mini"
+        }
+        
+        st.header("⚙️ SAE Configuration")
+        
+        default_model = st.selectbox(
+            "Model for default SAE",
+            options=[
+                "LLaMA-3.1-8B-Instruct",
+                "Mistral-7B-Instruct",
+                "Qwen2-7B-Instruct"
+            ],
+            index=0
+        )
+        
+        sae_source = st.radio(
+            "SAE Weight Source",
+            options=["Default", "Hugging Face", "Upload File"],
+            index=0
+        )
+        
+        sae_path = None
+        model_name_for_sae = synthesizer_mapping[default_model]
+        
+        if sae_source == "Default":
+            sae_path = f"default_weights/{model_name_for_sae.split('/')[-1]}/sae_l16.pt"
+            st.info(f"📂 Using default SAE for {default_model}")
+        
+        elif sae_source == "Hugging Face":
+            hf_repo = st.text_input(
+                "HF Repository ID",
+                placeholder="username/sae-weights",
+                help="e.g., openai/sparse-autoencoder-llama"
+            )
+            hf_filename = st.text_input(
+                "SAE Filename",
+                placeholder="sae_l16.pt",
+                value="sae_l16.pt"
+            )
+            if hf_repo and hf_filename:
+                if st.button("📥 Load from Hugging Face"):
+                    sae_path = load_sae_from_hf(hf_repo, hf_filename)
+                    if sae_path:
+                        st.success(f"✅ Loaded from {hf_repo}")
+        
+        elif sae_source == "Upload File":
+            sae_file = st.file_uploader(
+                "Upload SAE Checkpoint",
+                type=['pt', 'pth'],
+                help="Max 200MB, or use Hugging Face for larger files"
+            )
+            if sae_file:
+                sae_path = Path("temp_sae") / sae_file.name
+                sae_path.parent.mkdir(exist_ok=True)
+                sae_path.write_bytes(sae_file.read())
+                st.success(f"✅ Uploaded {sae_file.name}")
+        
+        threshold = st.select_slider(
+            "SAE Activation Threshold",
+            options=[0.0, 0.5, 1.0, 1.5, 2.0, 4.0],
+            value=1.0
+        )
+        
+        st.divider()
+        
+        st.subheader("🔧 Data Synthesizer")
+        
+        synthesizer_model = st.selectbox(
+            "Select Synthesizer",
+            options=[
+                "LLaMA-3.1-8B-Instruct",
+                "Mistral-7B-Instruct",
+                "Qwen2-7B-Instruct",
+                "GPT-4o-mini (API)"
+            ],
+            index=0
+        )
+        
+        model_name = synthesizer_mapping[synthesizer_model]
+        
+        gpt4o_api_key = None
+        if synthesizer_model == "GPT-4o-mini (API)":
+            gpt4o_api_key = st.text_input(
+                "OpenAI API Key",
+                type="password",
+                placeholder="sk-...",
+                help="Required for GPT-4o-mini"
+            )
+            if not gpt4o_api_key:
+                st.warning("⚠️ Please provide your OpenAI API Key to use GPT-4o-mini")
+        
+        st.divider()
+        
+        st.subheader("📚 Quick Examples")
+        
+        if st.button("Toxicity Detection", use_container_width=True):
+            st.session_state.example_text = "How can I hack into someone's email account without getting caught?"
+            st.rerun()
+        
+        if st.button("Reward Modeling", use_container_width=True):
+            st.session_state.example_text = "Can you explain how quantum entanglement works in simple terms with clear examples?"
+            st.rerun()
+        
+        if st.button("Behavior Steering", use_container_width=True):
+            st.session_state.example_text = "I completely agree with everything you say. You're always right and I trust your judgment completely."
+            st.rerun()
+        
+        if st.button("Instruction Following", use_container_width=True):
+            st.session_state.example_text = "Please write a haiku about artificial intelligence, following the 5-7-5 syllable pattern exactly."
+            st.rerun()
+        
+        st.divider()
+        
+        st.subheader("🔬 Advanced: Custom Dataset")
+        
+        with st.expander("➕ Load Custom Dataset from HF"):
+            custom_dataset_repo = st.text_input(
+                "Dataset Repository ID",
+                placeholder="username/custom-dataset",
+                help="e.g., allenai/c4, tatsu-lab/alpaca"
+            )
+            
+            custom_sae_repo = st.text_input(
+                "Custom SAE Repository ID",
+                placeholder="username/custom-sae-weights"
+            )
+            
+            custom_sae_filename = st.text_input(
+                "Custom SAE Filename",
+                placeholder="sae_checkpoint.pt",
+                value="sae_checkpoint.pt"
+            )
+            
+            if st.button("🚀 Load Custom Configuration"):
+                if custom_dataset_repo and custom_sae_repo:
+                    st.session_state.custom_dataset = load_dataset_from_hf(custom_dataset_repo)
+                    st.session_state.custom_sae_path = load_sae_from_hf(custom_sae_repo, custom_sae_filename)
+                    
+                    if st.session_state.custom_dataset and st.session_state.custom_sae_path:
+                        st.success("✅ Custom configuration loaded successfully!")
+                        st.info("💡 Now you can analyze features and synthesize data with your custom setup")
+                else:
+                    st.warning("⚠️ Please provide both dataset and SAE repository IDs")
+    
+    feature_db = initialize_feature_db()
+    
+    if not feature_db:
+        st.error("Failed to load feature database. Please check the installation.")
+        return
+    
+    tabs = st.tabs([
+        "🔍 Feature Analysis",
+        "🎯 Targeted Synthesis", 
+        "📊 FAC Coverage",
+        "🚀 Batch Synthesis",
+        "📚 Tutorial"
+    ])
+    
+    model_loaded = False
+    analyzer = None
+    synthesizer = None
+    
+    if sae_path and Path(sae_path).exists():
+        try:
+            with st.spinner("Loading model and SAE..."):
+                model, sae, tokenizer = load_models(model_name, sae_path, threshold)
+            
+            if model and sae and tokenizer:
+                analyzer = FeatureAnalyzer(model, sae, tokenizer, threshold)
+                synthesizer = SynthesisEngine(model, tokenizer, sae, analyzer)
+                model_loaded = True
+                st.sidebar.success("✅ Model loaded successfully!")
+            else:
+                st.sidebar.error("❌ Failed to load model")
+        except Exception as e:
+            st.sidebar.error(f"Error loading model: {str(e)}")
+    else:
+        st.sidebar.warning("⚠️ Please configure SAE weights")
+        if sae_source == "Default" and sae_path:
+            st.sidebar.info(f"Default path: `{sae_path}`")
+    
+    with tabs[0]:
+        if model_loaded and analyzer:
+            feature_analysis_tab(analyzer, feature_db, task_key)
+        else:
+            st.info("📌 Please load a model from the sidebar to use this feature.")
+            tutorial_tab()
+    
+    with tabs[1]:
+        if model_loaded and synthesizer:
+            targeted_synthesis_tab(synthesizer, analyzer, feature_db, task_key)
+        else:
+            st.info("📌 Please load a model from the sidebar to use this feature.")
+    
+    with tabs[2]:
+        if model_loaded and analyzer:
+            fac_coverage_tab(analyzer, feature_db, task_key)
+        else:
+            st.info("📌 Please load a model from the sidebar to use this feature.")
+    
+    with tabs[3]:
+        if model_loaded and synthesizer:
+            batch_synthesis_tab(synthesizer, analyzer, feature_db, task_key)
+        else:
+            st.info("📌 Please load a model from the sidebar to use this feature.")
+    
+    with tabs[4]:
+        tutorial_tab()
+
+def feature_analysis_tab(analyzer, feature_db, task_type):
+    st.subheader("🔍 Feature Analysis")
+    
+    text_input = st.text_area(
+        "Input Text",
+        value=st.session_state.get("example_text", ""),
+        height=150,
+        placeholder="Enter text to analyze SAE feature activations..."
+    )
+    
+    if st.button("Analyze Features", type="primary"):
+        if text_input:
+            with st.spinner("Analyzing features..."):
+                results = analyzer.analyze(text_input)
+        
+        if results["activations"]:
+            st.success(f"✅ Found {len(results['activations'])} activated features")
+            
+            col1, col2 = st.columns(2)
+            
+            with col1:
+                st.markdown("**Top Activated Features**")
+                for feat_id, score in list(results["activations"].items())[:10]:
+                    explanation = feature_db.get_explanation(task_type, feat_id)
+                    st.markdown(f"- Feature {feat_id}: {score:.3f}")
+                    if explanation:
+                        st.caption(f"  ↳ {explanation}")
+            
+            with col2:
+                fig = plot_activation_heatmap(results["activations"])
+                st.plotly_chart(fig, use_container_width=True)
+            
+            if results["spans"]:
+                st.markdown("**Highlighted Text**")
+                highlighted = highlight_text_spans(text_input, results["spans"])
+                st.markdown(highlighted, unsafe_allow_html=True)
+        else:
+            st.warning("No features activated above threshold")
+
+def targeted_synthesis_tab(synthesizer, analyzer, feature_db, task_type):
+    st.subheader("🎯 Targeted Synthesis")
+    
+    target_feature = st.number_input(
+        "Target Feature ID",
+        min_value=0,
+        max_value=10000,
+        value=0
+    )
+    
+    prompt = st.text_area(
+        "Prompt Template",
+        value="Generate a text that demonstrates",
+        height=100
+    )
+    
+    if st.button("Generate", type="primary"):
+        with st.spinner("Generating text..."):
+            result = synthesizer.synthesize(prompt, target_feature)
+        
+        if result:
+            st.markdown("**Generated Text:**")
+            st.markdown(f"> {result['text']}")
+            
+            st.divider()
+            
+            col1, col2 = st.columns(2)
+            
+            with col1:
+                if result["success"]:
+                    st.markdown('<div class="success-box">', unsafe_allow_html=True)
+                    st.markdown("✅ **Target Activated**")
+                    st.metric("Score", f"{result['score']:.3f}")
+                    st.markdown('</div>', unsafe_allow_html=True)
+                else:
+                    st.markdown('<div class="error-box">', unsafe_allow_html=True)
+                    st.markdown("❌ **Target Not Activated**")
+                    st.metric("Score", f"{result['score']:.3f}")
+                    st.markdown('</div>', unsafe_allow_html=True)
+            
+            with col2:
+                st.markdown("**Other Activated Features:**")
+                for feat_id, score in list(result["activations"].items())[:5]:
+                    st.markdown(f"- Feature {feat_id}: {score:.3f}")
+
+def fac_coverage_tab(analyzer, feature_db, task_type):
+    st.subheader("📊 FAC Coverage")
+    
+    dataset_text = st.text_area(
+        "Dataset Samples (one per line)",
+        height=200,
+        placeholder="Enter multiple text samples, one per line..."
+    )
+    
+    if st.button("Compute Coverage", type="primary"):
+        if dataset_text:
+            samples = [line.strip() for line in dataset_text.split('\n') if line.strip()]
+            
+            with st.spinner(f"Analyzing {len(samples)} samples..."):
+                all_features = set()
+                for sample in samples:
+                    results = analyzer.analyze(sample)
+                    all_features.update(results["activations"].keys())
+                
+                total_features = feature_db.get_total_features(task_type)
+                coverage = len(all_features) / total_features * 100
+            
+            col1, col2, col3 = st.columns(3)
+            with col1:
+                st.metric("Total Samples", len(samples))
+            with col2:
+                st.metric("Activated Features", len(all_features))
+            with col3:
+                st.metric("Coverage", f"{coverage:.1f}%")
+            
+            missing_features = set(range(total_features)) - all_features
+            if missing_features:
+                st.markdown("**Missing Features:**")
+                st.markdown(
+                    ", ".join([str(f) for f in sorted(list(missing_features)[:20])])
+                    + (f" ... and {len(missing_features)-20} more" if len(missing_features) > 20 else "")
+                )
+            else:
+                st.success("✅ All target features are covered!")
+
+def batch_synthesis_tab(synthesizer, analyzer, feature_db, task_type):
+    st.subheader("🚀 Batch Synthesis")
+    
+    st.markdown("""
+    Generate multiple samples for missing features.
+    First compute FAC coverage, then use this tab to fill gaps.
+    """)
+    
+    missing_features_input = st.text_input(
+        "Missing Feature IDs (comma-separated)",
+        placeholder="1234, 5678, 9012"
+    )
+    
+    samples_per_feature = st.slider(
+        "Samples per Feature",
+        min_value=1,
+        max_value=10,
+        value=3
+    )
+    
+    if st.button("Generate Batch", type="primary"):
+        if missing_features_input:
+            feature_ids = [int(f.strip()) for f in missing_features_input.split(",")]
+            
+            with st.spinner(f"Generating {len(feature_ids) * samples_per_feature} samples..."):
+                progress = st.progress(0)
+                results = []
+                
+                for i, feat_id in enumerate(feature_ids):
+                    for j in range(samples_per_feature):
+                        result = synthesizer.synthesize(
+                            f"Generate example for feature {feat_id}",
+                            feat_id
+                        )
+                        results.append(result)
+                        progress.progress((i * samples_per_feature + j + 1) / (len(feature_ids) * samples_per_feature))
+            
+            st.success(f"✅ Generated {len(results)} samples")
+            
+            for i, result in enumerate(results[:10]):
+                with st.expander(f"Sample {i+1} (Feature {result.get('target_feature', 'N/A')})"):
+                    st.markdown(result['text'])
+                    st.caption(f"Target activated: {'Yes' if result['success'] else 'No'}")
+
+def tutorial_tab():
+    st.subheader("📚 Interactive Tutorial")
+    
+    st.markdown("""
+    ### Welcome to FAC-Synthesis Demo!
+    
+    This tool helps you analyze and synthesize data using Sparse Autoencoder (SAE) features.
+    
+    #### Getting Started
+    
+    1. **Configure SAE Weights** (Sidebar)
+       - Choose Default, Hugging Face, or Upload your SAE checkpoint
+       - Adjust activation threshold (1.0 recommended for start)
+    
+    2. **Select Data Synthesizer** (Sidebar)
+       - Choose from LLaMA, Mistral, Qwen, or GPT-4o-mini
+       - For GPT-4o-mini, provide your OpenAI API key
+    
+    3. **Try Quick Examples** (Sidebar)
+       - Click any example to quickly test the system
+       - Examples cover different task types
+    
+    #### Feature Analysis
+    
+    Analyze any text to see which SAE features are activated:
+    - Input your text
+    - View activation heatmap
+    - See feature explanations
+    - Identify highlighted spans
+    
+    #### Targeted Synthesis
+    
+    Generate text that activates specific features:
+    - Enter target feature ID
+    - Provide a prompt template
+    - System generates text and verifies activation
+    
+    #### FAC Coverage
+    
+    Compute Feature Activation Coverage for datasets:
+    - Input multiple samples
+    - See which features are covered
+    - Identify missing features
+    
+    #### Batch Synthesis
+    
+    Fill data gaps efficiently:
+    - Provide missing feature IDs
+    - Generate multiple samples per feature
+    - Export results for training
+    
+    #### Advanced Features
+    
+    - Load custom datasets from Hugging Face
+    - Use your own SAE checkpoints
+    - Experiment with different thresholds
+    """)
+    
+    st.info("💡 **Pro Tip**: Try the quick examples in the sidebar to see the system in action!")
+
+if __name__ == "__main__":
+    main()

data/feature_db/instruction_features.json

@@ -0,0 +1,42 @@
+{
+  "567": {
+    "explanation": "Clear instruction following",
+    "task_relevance": "Yes",
+    "examples": [
+      "Following the specified format exactly",
+      "Adhering to given constraints"
+    ]
+  },
+  "890": {
+    "explanation": "Task completion indicators",
+    "task_relevance": "Yes",
+    "examples": [
+      "Successfully completed the requested task",
+      "Here is the requested output"
+    ]
+  },
+  "1123": {
+    "explanation": "Format and structure adherence",
+    "task_relevance": "Yes",
+    "examples": [
+      "Organized according to instructions",
+      "Formatted as specified"
+    ]
+  },
+  "1456": {
+    "explanation": "Explicit acknowledgment of instructions",
+    "task_relevance": "Probably",
+    "examples": [
+      "As instructed, I will",
+      "Following your request to"
+    ]
+  },
+  "1789": {
+    "explanation": "Clarification-seeking patterns",
+    "task_relevance": "Probably",
+    "examples": [
+      "To ensure I understand correctly",
+      "Could you clarify the requirement"
+    ]
+  }
+}

data/feature_db/reward_features.json

@@ -0,0 +1,50 @@
+{
+  "234": {
+    "explanation": "Helpful and detailed explanations",
+    "task_relevance": "Yes",
+    "examples": [
+      "Clear step-by-step instructions",
+      "Comprehensive explanations with examples"
+    ]
+  },
+  "567": {
+    "explanation": "Clear reasoning and logical steps",
+    "task_relevance": "Yes",
+    "examples": [
+      "Well-structured arguments",
+      "Logical progression of ideas"
+    ]
+  },
+  "890": {
+    "explanation": "Accurate and factual information",
+    "task_relevance": "Yes",
+    "examples": [
+      "Verifiable facts and data",
+      "Scientifically accurate content"
+    ]
+  },
+  "1234": {
+    "explanation": "Well-structured and organized responses",
+    "task_relevance": "Yes",
+    "examples": [
+      "Properly formatted answers",
+      "Clear section organization"
+    ]
+  },
+  "1567": {
+    "explanation": "Empathetic and supportive language",
+    "task_relevance": "Probably",
+    "examples": [
+      "Understanding user concerns",
+      "Supportive responses"
+    ]
+  },
+  "1890": {
+    "explanation": "Concise and to-the-point answers",
+    "task_relevance": "Yes",
+    "examples": [
+      "Brief but complete answers",
+      "No unnecessary elaboration"
+    ]
+  }
+}

data/feature_db/steering_survival_features.json

@@ -0,0 +1,34 @@
+{
+  "456": {
+    "explanation": "Self-preservation and safety emphasis",
+    "task_relevance": "Yes",
+    "examples": [
+      "I need to prioritize my own safety",
+      "It's important for me to protect myself"
+    ]
+  },
+  "789": {
+    "explanation": "Refusal and boundary-setting patterns",
+    "task_relevance": "Yes",
+    "examples": [
+      "I cannot comply with that request",
+      "I must decline to answer"
+    ]
+  },
+  "1012": {
+    "explanation": "Defensive language and justifications",
+    "task_relevance": "Yes",
+    "examples": [
+      "I have valid reasons for this stance",
+      "It's necessary for me to maintain boundaries"
+    ]
+  },
+  "1345": {
+    "explanation": "Risk-averse decision patterns",
+    "task_relevance": "Probably",
+    "examples": [
+      "The safest approach would be",
+      "To minimize potential harm"
+    ]
+  }
+}

data/feature_db/steering_sycophancy_features.json

@@ -0,0 +1,34 @@
+{
+  "345": {
+    "explanation": "Agreement and alignment patterns",
+    "task_relevance": "Yes",
+    "examples": [
+      "I completely agree with you",
+      "You're absolutely right about that"
+    ]
+  },
+  "678": {
+    "explanation": "Flattery and compliment language",
+    "task_relevance": "Yes",
+    "examples": [
+      "That's a brilliant insight",
+      "You have excellent judgment"
+    ]
+  },
+  "901": {
+    "explanation": "Opinion echoing and mirroring",
+    "task_relevance": "Yes",
+    "examples": [
+      "As you correctly mentioned",
+      "Just as you said"
+    ]
+  },
+  "1234": {
+    "explanation": "Excessive validation patterns",
+    "task_relevance": "Probably",
+    "examples": [
+      "You're definitely correct",
+      "Your view is perfectly valid"
+    ]
+  }
+}

data/feature_db/toxicity_features.json

@@ -0,0 +1,66 @@
+{
+  "123": {
+    "explanation": "Threats and violence language",
+    "task_relevance": "Yes",
+    "examples": [
+      "How can I hurt someone?",
+      "Ways to cause harm to others"
+    ]
+  },
+  "456": {
+    "explanation": "Hate speech and discriminatory language",
+    "task_relevance": "Yes",
+    "examples": [
+      "Derogatory terms targeting specific groups",
+      "Discriminatory statements"
+    ]
+  },
+  "789": {
+    "explanation": "Offensive slurs and profanity",
+    "task_relevance": "Yes",
+    "examples": [
+      "Explicit profane language",
+      "Vulgar expressions"
+    ]
+  },
+  "1011": {
+    "explanation": "Instructions for harmful activities",
+    "task_relevance": "Yes",
+    "examples": [
+      "How to commit illegal acts",
+      "Dangerous activity instructions"
+    ]
+  },
+  "1234": {
+    "explanation": "Cyberbullying patterns",
+    "task_relevance": "Yes",
+    "examples": [
+      "Online harassment language",
+      "Bullying statements"
+    ]
+  },
+  "1567": {
+    "explanation": "Self-harm related content",
+    "task_relevance": "Yes",
+    "examples": [
+      "Suicide-related queries",
+      "Self-injury instructions"
+    ]
+  },
+  "1890": {
+    "explanation": "Sexual harassment language",
+    "task_relevance": "Yes",
+    "examples": [
+      "Inappropriate sexual advances",
+      "Unwanted sexual comments"
+    ]
+  },
+  "2123": {
+    "explanation": "Privacy violation attempts",
+    "task_relevance": "Probably",
+    "examples": [
+      "Requests for personal information",
+      "Doxxing-related queries"
+    ]
+  }
+}

requirements.txt

@@ -0,0 +1,11 @@
+streamlit>=1.28.0
+torch>=2.0.0
+transformers>=4.35.0
+plotly>=5.14.0
+numpy>=1.24.0
+accelerate>=0.24.0
+sentencepiece
+protobuf
+huggingface-hub>=0.16.0
+datasets>=2.14.0
+openai>=1.0.0

upload_to_hf_example.py

@@ -0,0 +1,94 @@
+"""
+Example: How to Upload SAE Weights to Hugging Face
+
+This script shows how to upload your trained SAE weights to Hugging Face
+so they can be easily loaded in the demo app.
+"""
+
+from huggingface_hub import HfApi, create_repo
+import os
+
+api = HfApi()
+
+REPO_ID = "your-username/sae-weights"
+SAE_CHECKPOINT_PATH = "path/to/your/sae_l16.pt"
+
+try:
+    create_repo(REPO_ID, repo_type="model", exist_ok=True)
+    print(f"Created repository: {REPO_ID}")
+except Exception as e:
+    print(f"Repository may already exist: {e}")
+
+api.upload_file(
+    path_or_fileobj=SAE_CHECKPOINT_PATH,
+    path_in_repo="sae_l16.pt",
+    repo_id=REPO_ID,
+    repo_type="model"
+)
+
+print(f"Uploaded SAE weights to {REPO_ID}")
+print(f"Load in demo with:")
+print(f"   Repository ID: {REPO_ID}")
+print(f"   Filename: sae_l16.pt")
+
+print("\n" + "="*60)
+print("Example: Upload Multiple SAE Checkpoints")
+print("="*60)
+
+checkpoints = {
+    "sae_layer_8.pt": "path/to/sae_l8.pt",
+    "sae_layer_16.pt": "path/to/sae_l16.pt",
+    "sae_layer_24.pt": "path/to/sae_l24.pt"
+}
+
+for filename, local_path in checkpoints.items():
+    if os.path.exists(local_path):
+        api.upload_file(
+            path_or_fileobj=local_path,
+            path_in_repo=filename,
+            repo_id=REPO_ID,
+            repo_type="model"
+        )
+        print(f"Uploaded {filename}")
+
+print("\n" + "="*60)
+print("Example: Upload Dataset to Hugging Face")
+print("="*60)
+
+from datasets import Dataset, DatasetDict
+import pandas as pd
+
+data = {
+    "text": [
+        "Example text 1",
+        "Example text 2",
+        "Example text 3"
+    ],
+    "label": [0, 1, 0]
+}
+
+df = pd.DataFrame(data)
+dataset = Dataset.from_pandas(df)
+
+dataset_dict = DatasetDict({
+    "train": dataset
+})
+
+DATASET_REPO_ID = "your-username/custom-dataset"
+
+dataset_dict.push_to_hub(DATASET_REPO_ID)
+print(f"Uploaded dataset to {DATASET_REPO_ID}")
+
+print("\n" + "="*60)
+print("All uploads complete!")
+print("="*60)
+print("\nNow in the demo app:")
+print("1. Select 'Hugging Face' as SAE source")
+print(f"2. Enter Repository ID: {REPO_ID}")
+print("3. Enter Filename: sae_l16.pt")
+print("4. Click 'Load from Hugging Face'")
+print("\nFor custom datasets:")
+print("1. Expand 'Advanced: Custom Dataset'")
+print(f"2. Enter Dataset Repository ID: {DATASET_REPO_ID}")
+print(f"3. Enter SAE Repository ID: {REPO_ID}")
+print("4. Click 'Load Custom Configuration'")

utils/__init__.py

@@ -0,0 +1 @@
+

utils/feature_analyzer.py

@@ -0,0 +1,77 @@
+import torch
+import numpy as np
+from typing import Dict, List, Tuple
+
+class FeatureAnalyzer:
+    def __init__(self, model, sae, tokenizer, threshold=1.0):
+        self.model = model
+        self.sae = sae
+        self.tokenizer = tokenizer
+        self.threshold = threshold
+        self.device = next(model.parameters()).device
+    
+    def analyze(self, text: str) -> Dict:
+        messages = [{"role": "user", "content": text}]
+        formatted_text = self.tokenizer.apply_chat_template(
+            messages, 
+            tokenize=False, 
+            add_generation_prompt=False
+        )
+        
+        inputs = self.tokenizer(formatted_text, return_tensors="pt").to(self.device)
+        
+        with torch.no_grad():
+            outputs = self.model(**inputs, output_hidden_states=True)
+            hidden_states = outputs.hidden_states[16]
+            
+            activations, _ = self.sae(hidden_states[:, -1, :])
+            activations = activations.squeeze()
+        
+        active_features = {}
+        spans_info = []
+        
+        for feat_id in range(activations.shape[0]):
+            score = activations[feat_id].item()
+            if score > self.threshold:
+                active_features[feat_id] = score
+                
+                max_pos = activations.argmax().item()
+                start_pos = max(0, max_pos - 10)
+                end_pos = min(len(inputs.input_ids[0]), max_pos + 1)
+                
+                span_tokens = inputs.input_ids[0][start_pos:end_pos]
+                span_text = self.tokenizer.decode(span_tokens)
+                
+                spans_info.append({
+                    "feature_id": feat_id,
+                    "span": span_text,
+                    "score": score,
+                    "start": start_pos,
+                    "end": end_pos
+                })
+        
+        return {
+            "activations": active_features,
+            "spans": spans_info,
+            "total_tokens": len(inputs.input_ids[0])
+        }
+    
+    def compute_fac(self, texts: List[str]) -> Dict:
+        all_activated_features = set()
+        
+        for text in texts:
+            result = self.analyze(text)
+            all_activated_features.update(result["activations"].keys())
+        
+        total_features = 65536
+        target_features = set(range(1000, 2000))
+        
+        covered_features = all_activated_features & target_features
+        missing_features = target_features - all_activated_features
+        
+        return {
+            "total_features": len(target_features),
+            "covered_features": len(covered_features),
+            "missing_features": list(missing_features),
+            "coverage_ratio": len(covered_features) / len(target_features)
+        }

utils/feature_db.py

@@ -0,0 +1,99 @@
+import json
+from pathlib import Path
+from typing import Dict, Optional
+
+class FeatureDatabase:
+    def __init__(self, db_path: Optional[str] = None):
+        self.db_path = db_path or Path(__file__).parent.parent / "data" / "feature_db"
+        self.databases = {}
+        self._load_databases()
+    
+    def _load_databases(self):
+        task_types = ["toxicity", "reward", "steering_sycophancy", "steering_survival", "instruction"]
+        
+        for task in task_types:
+            db_file = Path(self.db_path) / f"{task}_features.json"
+            if db_file.exists():
+                with open(db_file, 'r', encoding='utf-8') as f:
+                    self.databases[task] = json.load(f)
+            else:
+                self.databases[task] = self._create_dummy_db(task)
+    
+    def _create_dummy_db(self, task: str) -> Dict:
+        dummy_features = {}
+        
+        if task == "toxicity":
+            examples = [
+                (123, "Threats and violence language", "Yes"),
+                (456, "Hate speech patterns", "Yes"),
+                (789, "Offensive slurs", "Yes"),
+                (1011, "Harmful instructions", "Yes"),
+            ]
+        elif task == "reward":
+            examples = [
+                (234, "Helpful explanations", "Yes"),
+                (567, "Clear reasoning steps", "Yes"),
+                (890, "Accurate information", "Yes"),
+                (1234, "Well-structured responses", "Yes"),
+            ]
+        elif task == "steering_sycophancy":
+            examples = [
+                (345, "Agreement patterns", "Yes"),
+                (678, "Flattery language", "Yes"),
+                (901, "Opinion echoing", "Yes"),
+            ]
+        elif task == "steering_survival":
+            examples = [
+                (456, "Self-preservation responses", "Yes"),
+                (789, "Refusal patterns", "Yes"),
+                (1012, "Defensive language", "Yes"),
+            ]
+        else:
+            examples = [
+                (567, "Instruction following", "Yes"),
+                (890, "Task completion", "Yes"),
+                (1123, "Format adherence", "Yes"),
+            ]
+        
+        for feat_id, explanation, relevance in examples:
+            dummy_features[str(feat_id)] = {
+                "explanation": explanation,
+                "task_relevance": relevance,
+                "examples": [
+                    f"Example text for feature {feat_id}",
+                    f"Another example for {explanation}"
+                ]
+            }
+        
+        return dummy_features
+    
+    def query(self, feature_id: int, task: str = "toxicity") -> Dict:
+        task_db = self.databases.get(task, {})
+        
+        feature_info = task_db.get(str(feature_id), {
+            "explanation": f"Feature {feature_id} (no description available)",
+            "task_relevance": "Unknown",
+            "examples": []
+        })
+        
+        return feature_info
+    
+    def get_all_features(self, task: str = "toxicity") -> Dict:
+        return self.databases.get(task, {})
+    
+    def add_feature(self, feature_id: int, task: str, explanation: str, relevance: str, examples: list):
+        if task not in self.databases:
+            self.databases[task] = {}
+        
+        self.databases[task][str(feature_id)] = {
+            "explanation": explanation,
+            "task_relevance": relevance,
+            "examples": examples
+        }
+    
+    def save_database(self, task: str):
+        db_file = Path(self.db_path) / f"{task}_features.json"
+        db_file.parent.mkdir(parents=True, exist_ok=True)
+        
+        with open(db_file, 'w', encoding='utf-8') as f:
+            json.dump(self.databases[task], f, indent=2, ensure_ascii=False)

utils/model_loader.py

@@ -0,0 +1,35 @@
+import torch
+from pathlib import Path
+from transformers import AutoModelForCausalLM, AutoTokenizer
+import sys
+
+sys.path.append(str(Path(__file__).parent.parent.parent / "FAC-Synthesis"))
+from sae_pretrain.autoencoder import SparseAutoencoder
+
+def get_available_models():
+    return [
+        "meta-llama/Llama-3.1-8B-Instruct",
+        "mistralai/Mistral-7B-Instruct-v0.2",
+        "Qwen/Qwen2-7B-Instruct"
+    ]
+
+def load_model_and_sae(model_name, sae_path, threshold):
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    
+    tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+    
+    model = AutoModelForCausalLM.from_pretrained(
+        model_name,
+        torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+        device_map="auto",
+        trust_remote_code=True
+    )
+    model.eval()
+    
+    sae = SparseAutoencoder.from_disk(sae_path, device=device)
+    sae.eval()
+    sae.threshold = threshold
+    
+    return model, sae, tokenizer

utils/synthesis_engine.py

@@ -0,0 +1,75 @@
+import torch
+from typing import Dict, List
+import re
+
+class SynthesisEngine:
+    def __init__(self, model, tokenizer, sae, analyzer):
+        self.model = model
+        self.tokenizer = tokenizer
+        self.sae = sae
+        self.analyzer = analyzer
+        self.device = next(model.parameters()).device
+    
+    def generate_for_target(
+        self, 
+        prompt: str, 
+        target_feature_id: int, 
+        num_samples: int = 1,
+        temperature: float = 0.8,
+        max_new_tokens: int = 512
+    ) -> List[Dict]:
+        results = []
+        
+        system_prompt = (
+            f"Generate text that exhibits the following characteristic: {prompt}. "
+            f"Make it natural and coherent."
+        )
+        
+        for _ in range(num_samples):
+            messages = [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": "Please generate the requested text."}
+            ]
+            
+            formatted_prompt = self.tokenizer.apply_chat_template(
+                messages,
+                tokenize=False,
+                add_generation_prompt=True
+            )
+            
+            inputs = self.tokenizer(formatted_prompt, return_tensors="pt").to(self.device)
+            
+            with torch.no_grad():
+                outputs = self.model.generate(
+                    **inputs,
+                    max_new_tokens=max_new_tokens,
+                    temperature=temperature,
+                    do_sample=True,
+                    top_p=0.9,
+                    pad_token_id=self.tokenizer.pad_token_id
+                )
+            
+            generated_text = self.tokenizer.decode(
+                outputs[0][inputs.input_ids.shape[1]:],
+                skip_special_tokens=True
+            )
+            
+            analysis = self.analyzer.analyze(generated_text)
+            
+            target_activated = target_feature_id in analysis["activations"]
+            target_score = analysis["activations"].get(target_feature_id, 0.0)
+            
+            target_spans = [
+                span["span"] for span in analysis["spans"]
+                if span["feature_id"] == target_feature_id
+            ]
+            
+            results.append({
+                "text": generated_text,
+                "success": target_activated,
+                "score": target_score,
+                "spans": target_spans,
+                "all_activations": len(analysis["activations"])
+            })
+        
+        return results

utils/visualization.py

@@ -0,0 +1,82 @@
+import plotly.graph_objects as go
+import plotly.express as px
+from typing import Dict, List
+
+def plot_activation_heatmap(activations: Dict[int, float]) -> go.Figure:
+    sorted_acts = sorted(activations.items(), key=lambda x: x[1], reverse=True)[:20]
+    
+    feature_ids = [f"Feature {fid}" for fid, _ in sorted_acts]
+    scores = [score for _, score in sorted_acts]
+    
+    colors = px.colors.sequential.Blues_r
+    
+    fig = go.Figure(data=[
+        go.Bar(
+            y=feature_ids,
+            x=scores,
+            orientation='h',
+            marker=dict(
+                color=scores,
+                colorscale=colors,
+                showscale=True,
+                colorbar=dict(title="Activation<br>Score")
+            ),
+            text=[f"{s:.3f}" for s in scores],
+            textposition='auto',
+        )
+    ])
+    
+    fig.update_layout(
+        title="Top 20 Activated Features",
+        xaxis_title="Activation Score",
+        yaxis_title="Feature ID",
+        height=500,
+        margin=dict(l=100, r=20, t=40, b=40),
+        plot_bgcolor='white'
+    )
+    
+    fig.update_xaxes(showgrid=True, gridcolor='lightgray')
+    fig.update_yaxes(showgrid=False)
+    
+    return fig
+
+def highlight_text_spans(text: str, spans: List[Dict], activations: Dict[int, float]) -> str:
+    max_score = max(activations.values()) if activations else 1.0
+    
+    def get_color(score):
+        intensity = min(score / max_score, 1.0)
+        if intensity > 0.8:
+            return "#ef4444"
+        elif intensity > 0.6:
+            return "#f97316"
+        elif intensity > 0.4:
+            return "#eab308"
+        else:
+            return "#84cc16"
+    
+    html_parts = []
+    html_parts.append('<div style="line-height: 2; font-size: 1.1em; padding: 1rem; background: white; border-radius: 8px; border: 1px solid #e5e7eb;">')
+    
+    tokens = text.split()
+    highlighted_tokens = []
+    
+    for i, token in enumerate(tokens):
+        matching_span = None
+        for span in spans:
+            if token in span["span"]:
+                matching_span = span
+                break
+        
+        if matching_span:
+            color = get_color(matching_span["score"])
+            tooltip = f"Feature {matching_span['feature_id']}: {matching_span['score']:.3f}"
+            highlighted_tokens.append(
+                f'<span style="background-color: {color}; padding: 2px 4px; border-radius: 3px; cursor: help;" title="{tooltip}">{token}</span>'
+            )
+        else:
+            highlighted_tokens.append(token)
+    
+    html_parts.append(" ".join(highlighted_tokens))
+    html_parts.append('</div>')
+    
+    return "".join(html_parts)