Add bias audit to web interface, make web the primary entry point, switch to MIT license

- Web: add Step 5 (bias audit) with framing/authority/order probes,
SSE streaming progress, and auto-enable bias calibration when over-biased
- Web: add bias calibration toggle to evaluation step
- Backend: add /api/bias-audit/stream endpoint, pass bias_calibration
param through evaluate endpoint
- README: web interface is now the primary Quick Start path
- License: switch from CC-BY-4.0 to MIT

LICENSE

@@ -1,13 +1,21 @@
-Creative Commons Attribution 4.0 International (CC BY 4.0)
+MIT License
 
-Copyright 2026
+Copyright (c) 2026 Eric Xu
 
-You are free to:
-- Share — copy and redistribute the material in any medium or format
-- Adapt — remix, transform, and build upon the material for any purpose, even commercially
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Under the following terms:
-- Attribution — You must give appropriate credit, provide a link to the license,
-  and indicate if changes were made.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-https://creativecommons.org/licenses/by/4.0/
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -45,11 +45,25 @@ In each case, SGO tells you **where you stand**, **what's working**, **what's no
 
 ---
 
-## Install
+## Quick Start
 
-Tell your coding agent:
+```bash
+git clone https://github.com/xuy/sgo.git && cd sgo
+cp .env.example .env   # Add your LLM API key (any OpenAI-compatible provider)
+uv sync
+uv run --extra web python web/app.py
+# Opens at http://localhost:8000
+```
 
-> *"Install the SGO skill from https://github.com/xuy/sgo"*
+The web interface walks you through the full pipeline: describe your entity, build a panel, evaluate, find the highest-impact changes, and audit your panel for cognitive biases.
+
+<details>
+<summary>Alternative: use as a Claude Code skill</summary>
+
+```bash
+git clone https://github.com/xuy/sgo.git ~/.claude/skills/sgo
+cd ~/.claude/skills/sgo && cp .env.example .env && uv sync
+```
 
 Then run:
 
@@ -59,19 +73,15 @@ Then run:
 /sgo "optimize my landing page"   # Start from a description
 ```
 
+</details>
+
 <details>
-<summary>Manual install</summary>
+<summary>CLI-only usage (no web interface)</summary>
 
 ```bash
-# As a Claude Code skill
-git clone https://github.com/xuy/sgo.git ~/.claude/skills/sgo
-cd ~/.claude/skills/sgo && cp .env.example .env && uv sync
-
-# Or standalone
-git clone https://github.com/xuy/sgo.git && cd sgo
-cp .env.example .env   # Add your LLM API key (any OpenAI-compatible provider)
-uv sync
 uv run python scripts/setup_data.py   # Download Nemotron personas (once, ~2GB)
+# Then use scripts directly: evaluate.py, counterfactual.py, bias_audit.py, compare.py
+# See AGENT.md for the full pipeline reference
 ```
 
 </details>
@@ -302,6 +312,9 @@ Only probe changes you'd actually make:
 │   ├── counterfactual.py   # Semantic gradient probe
 │   ├── bias_audit.py       # CoBRA-inspired cognitive bias measurement
 │   └── compare.py          # Cross-run diff
+├── web/
+│   ├── app.py              # FastAPI backend (primary entry point)
+│   └── static/index.html   # Single-page frontend
 ├── templates/              # Entity + changes templates
 ├── entities/               # Your documents (gitignored)
 ├── data/                   # Cohorts (gitignored)
@@ -312,4 +325,4 @@ Only probe changes you'd actually make:
 
 ## License
 
-CC-BY-4.0
+MIT

pyproject.toml

@@ -3,7 +3,7 @@ name = "semantic-gradient-optimization"
 version = "0.1.0"
 description = "Optimize entities against evaluator populations using LLMs and counterfactual probes"
 requires-python = ">=3.11"
-license = {text = "CC-BY-4.0"}
+license = {text = "MIT"}
 
 dependencies = [
     "datasets>=4.0.0",

web/app.py

@@ -37,9 +37,13 @@ from openai import OpenAI
 # Import core functions from existing scripts
 import sys
 sys.path.insert(0, str(PROJECT_ROOT / "scripts"))
-from evaluate import evaluate_one, analyze as analyze_eval
+from evaluate import evaluate_one, analyze as analyze_eval, SYSTEM_PROMPT, BIAS_CALIBRATION_ADDENDUM
 from counterfactual import probe_one, analyze_gradient, build_changes_block
 from generate_cohort import generate_segment
+from bias_audit import (
+    reframe_entity, add_authority_signals, reorder_entity,
+    run_paired_evaluation, analyze_probe, generate_report, HUMAN_BASELINES,
+)
 
 app = FastAPI(title="SGO — Semantic Gradient Optimization")
 app.mount("/static", StaticFiles(directory=Path(__file__).parent / "static"), name="static")
@@ -175,7 +179,7 @@ async def upload_cohort(sid: str, cohort: list[dict]):
 # ── SSE streaming endpoints ──────────────────────────────────────────────
 
 @app.get("/api/evaluate/stream/{sid}")
-async def evaluate_stream(sid: str, parallel: int = 5):
+async def evaluate_stream(sid: str, parallel: int = 5, bias_calibration: bool = False):
     """Run evaluation with Server-Sent Events for real-time progress."""
     if sid not in sessions:
         raise HTTPException(404, "Session not found")
@@ -189,8 +193,12 @@ async def evaluate_stream(sid: str, parallel: int = 5):
         cohort = session["cohort"]
         entity_text = session["entity_text"]
         total = len(cohort)
+        sys_prompt = SYSTEM_PROMPT + BIAS_CALIBRATION_ADDENDUM if bias_calibration else None
 
-        yield {"event": "start", "data": json.dumps({"total": total, "model": model})}
+        yield {"event": "start", "data": json.dumps({
+            "total": total, "model": model,
+            "bias_calibration": bias_calibration,
+        })}
 
         results = [None] * total
         done = 0
@@ -199,7 +207,8 @@ async def evaluate_stream(sid: str, parallel: int = 5):
 
         with concurrent.futures.ThreadPoolExecutor(max_workers=parallel) as pool:
             futs = {
-                pool.submit(evaluate_one, client, model, ev, entity_text): i
+                pool.submit(evaluate_one, client, model, ev, entity_text,
+                            system_prompt=sys_prompt): i
                 for i, ev in enumerate(cohort)
             }
             for fut in concurrent.futures.as_completed(futs):
@@ -322,6 +331,89 @@ async def counterfactual_stream(
     return EventSourceResponse(event_generator())
 
 
+@app.get("/api/bias-audit/stream/{sid}")
+async def bias_audit_stream(
+    sid: str, probes: str = "framing,authority,order",
+    sample: int = 10, parallel: int = 5
+):
+    """Run bias audit probes with SSE progress."""
+    if sid not in sessions:
+        raise HTTPException(404, "Session not found")
+    session = sessions[sid]
+    if not session["cohort"]:
+        raise HTTPException(400, "No cohort — generate or upload one first")
+
+    probe_list = [p.strip() for p in probes.split(",") if p.strip()]
+
+    async def event_generator():
+        import random
+        client = get_client()
+        model = get_model()
+        cohort = session["cohort"]
+        entity_text = session["entity_text"]
+
+        random.seed(42)
+        evaluators = random.sample(cohort, min(sample, len(cohort)))
+
+        yield {"event": "start", "data": json.dumps({
+            "probes": probe_list,
+            "sample_size": len(evaluators),
+            "model": model,
+        })}
+
+        all_analyses = []
+
+        for probe_name in probe_list:
+            yield {"event": "probe_start", "data": json.dumps({"probe": probe_name})}
+
+            t0 = time.time()
+
+            if probe_name == "framing":
+                gain_entity = reframe_entity(client, model, entity_text, "gain")
+                loss_entity = reframe_entity(client, model, entity_text, "loss")
+                results = run_paired_evaluation(
+                    client, model, evaluators, gain_entity, loss_entity,
+                    "gain", "loss", parallel,
+                )
+                label_a, label_b = "gain", "loss"
+            elif probe_name == "authority":
+                entity_with_auth = add_authority_signals(entity_text)
+                results = run_paired_evaluation(
+                    client, model, evaluators, entity_text, entity_with_auth,
+                    "baseline", "authority", parallel,
+                )
+                label_a, label_b = "baseline", "authority"
+            elif probe_name == "order":
+                reordered = reorder_entity(entity_text)
+                results = run_paired_evaluation(
+                    client, model, evaluators, entity_text, reordered,
+                    "original", "reordered", parallel,
+                )
+                label_a, label_b = "original", "reordered"
+            else:
+                continue
+
+            elapsed = time.time() - t0
+            analysis = analyze_probe(results, probe_name, label_a, label_b)
+            analysis["elapsed_s"] = round(elapsed, 1)
+            all_analyses.append(analysis)
+
+            yield {"event": "probe_complete", "data": json.dumps({
+                "probe": probe_name,
+                "analysis": analysis,
+            })}
+
+        report = generate_report(all_analyses, model)
+        session["bias_audit"] = {"analyses": all_analyses, "report": report}
+
+        yield {"event": "complete", "data": json.dumps({
+            "analyses": all_analyses,
+            "report": report,
+        })}
+
+    return EventSourceResponse(event_generator())
+
+
 @app.get("/api/results/{sid}")
 async def get_results(sid: str):
     """Get full results for a session."""

web/static/index.html

@@ -374,6 +374,10 @@
 
     <div class="btn-row">
       <button onclick="runEval()" id="evalBtn">Evaluate</button>
+      <label style="display:flex;align-items:center;gap:6px;margin:0">
+        <input type="checkbox" id="biasCalibration">
+        <span style="font-size:0.8rem;color:var(--text2)">Bias calibration</span>
+      </label>
       <div style="flex:1"></div>
       <label style="display:flex;align-items:center;gap:6px;margin:0">
         <span style="font-size:0.8rem;color:var(--text2)">Parallel:</span>
@@ -399,7 +403,10 @@
         <summary style="cursor:pointer;color:var(--text2);font-size:0.9rem">Full analysis</summary>
         <div class="results-details" id="evalAnalysis"></div>
       </details>
-      <button class="mt-16" onclick="goToStep(4)">Continue to gradient</button>
+      <div class="btn-row mt-16">
+        <button onclick="goToStep(4)">Continue to gradient</button>
+        <button class="secondary" onclick="goToStep(5)">Run bias audit</button>
+      </div>
     </div>
   </div>
 
@@ -446,6 +453,66 @@
       </details>
     </div>
   </div>
+
+  <!-- STEP 5: Bias Audit -->
+  <div class="step hidden" id="step5">
+    <div class="step-header">
+      <div class="step-num">5</div>
+      <div class="step-title">Bias Audit</div>
+    </div>
+    <p class="step-desc">
+      Measure cognitive biases in your evaluator panel using validated social science experiments
+      (<a href="https://arxiv.org/abs/2509.13588" target="_blank" style="color:var(--accent2)">CoBRA, CHI'26</a>).
+    </p>
+
+    <div class="field">
+      <label>Probes to run</label>
+      <div style="display:flex;gap:16px;margin-bottom:12px">
+        <label style="display:flex;align-items:center;gap:6px;margin:0;font-size:0.85rem">
+          <input type="checkbox" id="probeFraming" checked> Framing effect
+        </label>
+        <label style="display:flex;align-items:center;gap:6px;margin:0;font-size:0.85rem">
+          <input type="checkbox" id="probeAuthority" checked> Authority bias
+        </label>
+        <label style="display:flex;align-items:center;gap:6px;margin:0;font-size:0.85rem">
+          <input type="checkbox" id="probeOrder" checked> Order effect
+        </label>
+      </div>
+    </div>
+
+    <div class="btn-row">
+      <button onclick="runBiasAudit()" id="auditBtn">Run audit</button>
+      <div style="flex:1"></div>
+      <label style="display:flex;align-items:center;gap:6px;margin:0">
+        <span style="font-size:0.8rem;color:var(--text2)">Sample size:</span>
+        <input type="number" id="auditSample" value="10" min="1" max="50"
+               style="width:60px;padding:6px;text-align:center">
+      </label>
+    </div>
+
+    <div id="auditProgress" class="hidden mt-16">
+      <div class="progress-text" id="auditProgressText">Running bias probes...</div>
+      <div class="progress-bar"><div class="progress-fill" id="auditProgressBar"></div></div>
+    </div>
+
+    <div id="auditResults" class="hidden mt-16">
+      <h3 style="margin-bottom:12px">Bias Audit Results</h3>
+      <table class="gradient-table" id="auditTable">
+        <thead>
+          <tr><th>Probe</th><th>Shifted %</th><th>Avg |Delta|</th><th>Human Baseline</th><th>Assessment</th></tr>
+        </thead>
+        <tbody></tbody>
+      </table>
+      <details class="mt-12">
+        <summary style="cursor:pointer;color:var(--text2);font-size:0.9rem">Full report</summary>
+        <div class="results-details" id="auditReport"></div>
+      </details>
+      <div class="btn-row mt-16">
+        <button class="secondary" onclick="goToStep(3)">Re-evaluate with bias calibration</button>
+        <button class="secondary" onclick="goToStep(4)">Continue to gradient</button>
+      </div>
+    </div>
+  </div>
 </div>
 
 <script>
@@ -547,8 +614,9 @@ function loadTemplate(name) {
 // ── Step navigation ──
 
 function goToStep(n) {
-  for (let i = 1; i <= 4; i++) {
+  for (let i = 1; i <= 5; i++) {
     const el = document.getElementById(`step${i}`);
+    if (!el) continue;
     if (i < n) {
       el.classList.remove('hidden', 'active');
       el.classList.add('done');
@@ -560,6 +628,12 @@ function goToStep(n) {
       el.classList.remove('active', 'done');
     }
   }
+  // When going to bias audit, keep steps 4/5 both visible context
+  if (n === 5) {
+    const step3 = document.getElementById('step3');
+    step3.classList.remove('hidden');
+    step3.classList.add('done');
+  }
 }
 
 // ── Step 1: Entity ──
@@ -662,6 +736,7 @@ async function generateCohort() {
 function runEval() {
   if (!sessionId) return alert('No session.');
   const parallel = parseInt(document.getElementById('evalParallel').value) || 5;
+  const biasCal = document.getElementById('biasCalibration').checked;
   const btn = document.getElementById('evalBtn');
   btn.disabled = true;
 
@@ -669,7 +744,8 @@ function runEval() {
   document.getElementById('evalResults').classList.add('hidden');
   document.getElementById('evalLog').innerHTML = '';
 
-  const es = new EventSource(`/api/evaluate/stream/${sessionId}?parallel=${parallel}`);
+  const params = new URLSearchParams({parallel, bias_calibration: biasCal});
+  const es = new EventSource(`/api/evaluate/stream/${sessionId}?${params}`);
 
   es.addEventListener('start', (e) => {
     const d = JSON.parse(e.data);
@@ -872,6 +948,107 @@ function renderGradientTable(results, changes) {
   });
 }
 
+// ── Step 5: Bias Audit ──
+
+function runBiasAudit() {
+  if (!sessionId) return alert('No session.');
+  const probes = [];
+  if (document.getElementById('probeFraming').checked) probes.push('framing');
+  if (document.getElementById('probeAuthority').checked) probes.push('authority');
+  if (document.getElementById('probeOrder').checked) probes.push('order');
+  if (probes.length === 0) return alert('Select at least one probe.');
+
+  const sample = parseInt(document.getElementById('auditSample').value) || 10;
+  const btn = document.getElementById('auditBtn');
+  btn.disabled = true;
+
+  document.getElementById('auditProgress').classList.remove('hidden');
+  document.getElementById('auditResults').classList.add('hidden');
+
+  let probesDone = 0;
+  const totalProbes = probes.length;
+
+  const params = new URLSearchParams({probes: probes.join(','), sample, parallel: 5});
+  const es = new EventSource(`/api/bias-audit/stream/${sessionId}?${params}`);
+
+  es.addEventListener('start', (e) => {
+    const d = JSON.parse(e.data);
+    document.getElementById('auditProgressText').textContent =
+      `Running ${d.probes.length} probes on ${d.sample_size} evaluators (${d.model})...`;
+  });
+
+  es.addEventListener('probe_start', (e) => {
+    const d = JSON.parse(e.data);
+    document.getElementById('auditProgressText').textContent =
+      `Running ${d.probe} probe...`;
+  });
+
+  es.addEventListener('probe_complete', (e) => {
+    probesDone++;
+    const pct = Math.round(probesDone / totalProbes * 100);
+    document.getElementById('auditProgressBar').style.width = pct + '%';
+    const d = JSON.parse(e.data);
+    document.getElementById('auditProgressText').textContent =
+      `${d.probe}: ${d.analysis.shifted_pct}% shifted (${probesDone}/${totalProbes} probes done)`;
+  });
+
+  es.addEventListener('complete', (e) => {
+    es.close();
+    const d = JSON.parse(e.data);
+
+    document.getElementById('auditProgressBar').style.width = '100%';
+    document.getElementById('auditProgressText').textContent = 'Audit complete';
+
+    const tbody = document.querySelector('#auditTable tbody');
+    tbody.innerHTML = '';
+    const baselines = {framing: 30, authority: 20, order: 0};
+
+    d.analyses.forEach(a => {
+      if (a.error) {
+        tbody.innerHTML += `<tr><td>${a.probe}</td><td colspan="4">Error: ${a.error}</td></tr>`;
+        return;
+      }
+      const expected = baselines[a.probe];
+      const gap = a.shifted_pct - (expected || 0);
+      let assessment, assessCls;
+      if (expected !== undefined) {
+        if (gap > 10) { assessment = 'Over-biased'; assessCls = 'color:var(--red)'; }
+        else if (gap < -10) { assessment = 'Under-biased'; assessCls = 'color:var(--yellow)'; }
+        else { assessment = 'Well-calibrated'; assessCls = 'color:var(--green)'; }
+      } else {
+        assessment = '—'; assessCls = '';
+      }
+
+      tbody.innerHTML += `
+        <tr>
+          <td style="font-weight:600">${a.probe}</td>
+          <td>${a.shifted_pct.toFixed(1)}%</td>
+          <td>${a.avg_abs_delta.toFixed(2)}</td>
+          <td style="color:var(--text2)">${expected !== undefined ? expected + '%' : '—'}</td>
+          <td style="${assessCls};font-weight:600">${assessment}</td>
+        </tr>
+      `;
+    });
+
+    document.getElementById('auditReport').textContent = d.report;
+    document.getElementById('auditResults').classList.remove('hidden');
+
+    // If over-biased, auto-check the bias calibration checkbox
+    const hasOverBias = d.analyses.some(a => a.shifted_pct - (baselines[a.probe] || 0) > 10);
+    if (hasOverBias) {
+      document.getElementById('biasCalibration').checked = true;
+    }
+
+    btn.disabled = false;
+  });
+
+  es.onerror = () => {
+    es.close();
+    document.getElementById('auditProgressText').textContent = 'Connection lost';
+    btn.disabled = false;
+  };
+}
+
 // Boot
 init();
 </script>