README.md

metadata

title: FairnessScope
emoji: ⚖️
colorFrom: blue
colorTo: purple
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: AI fairness and threshold simulator.

FairnessScope

Model Evaluation & Fairness Diagnostics Studio | Hugdrigo Project #112

Short description: AI fairness and threshold simulator.

FairnessScope is an interactive, entirely client-side laboratory for exploring binary classification diagnostics across two fictional, non-demographic groups. It computes confusion matrices, selection rates, error-rate gaps, comparative thresholds, and illustrative false-positive/false-negative costs. This project is a transparent educational simulator, not a fairness certification, legal assessment, or trained AI model.

What it does

• Executive dashboard for accuracy, selection gap, true-positive-rate (TPR) gap, and confusion matrices.
• Interactive threshold laboratory with editable false-positive and false-negative costs.
• Configurable policy presets: inclusive (35%), balanced (50%), conservative (70%), and custom (5%–95%).
• Threshold curves for group selection rates, normalized error cost, and selection-rate gap.
• Group explorer: sample count, positive-label prevalence, selection rate, TPR, FPR, precision, accuracy, and outcome composition.
• Editable 160-record synthetic dataset: add, edit, archive and restore without deleting individual records.
• Search and filter the record library, export CSV, export and validate JSON backup, and manually restore data.
• Dark theme, responsive desktop/mobile layout, browser-local persistence and no external libraries, APIs, model downloads, authentication or paid services.

Hugging Face publication

1. Open https://huggingface.co/new-space under Hugdrigo.
2. Space name: fairnessscope-model-evaluation-studio.
3. Select Static SDK, blank template, Public visibility, and MIT license.
4. Upload README.md, index.html, and LICENSE to the repository root.
5. Commit changes. Hugging Face serves the application from index.html.

The YAML uses valid, explicitly allowed Hugging Face color values: colorFrom: blue and colorTo: purple. No API keys or environment secrets are required.

Local use

Open index.html in a modern browser. If local-file permissions limit browser storage, launch a local server (python3 -m http.server 8000 in the project folder), then visit http://localhost:8000.

Data provenance

The app generates exactly 160 deterministic fictional observations, 80 in each abstract cohort (A and B), from a fixed pseudorandom seed. Each record stores id, group, an integer score from 0–100, binary label (0/1), and archived (boolean). Outcomes are synthetic and provide no evidence about real groups, institutions, demographic categories, model fairness, discrimination, or legal compliance. The two group names deliberately do not denote protected or sensitive traits.

Decision rule: predict positive if score >= threshold.

At each threshold the confusion matrix tracks TP, TN, FP, FN. Undefined rates where a denominator is zero display as —.

Group metrics:

• Selection rate = (TP + FP) / N
• Base rate = (TP + FN) / N
• TPR / recall = TP / (TP + FN)
• FPR = FP / (FP + TN)
• Precision = TP / (TP + FP)
• Accuracy = (TP + TN) / N
• Demographic parity gap = absolute difference between the two groups' selection rates.
• Equal opportunity gap = absolute difference between their TPRs.
• Equalized odds diagnostic = greater of absolute TPR gap and absolute FPR gap.
• Weighted error cost = FP * configured FP cost + FN * configured FN cost, with cost units purely hypothetical.

The line chart's error cost is normalized to its own highest plotted value, while its second line shows the selection gap in percentage points. Therefore the lines are visualization aids, not common-unit financial measures. The scenario comparison table displays raw costs.

Limits and warnings

• These metrics are descriptive, not prescriptive, and are not a guarantee of fairness or an automated approval process. No normative pass/fail threshold is assigned.
• Fairness definitions may be incompatible in populations with different base rates. Measurement quality, group selection, uncertainty, and downstream impacts require contextual analysis.
• Synthetic labels and classifier scores are intentionally simplified. Results cannot be generalized to real operational decision systems.
• No confidence intervals, causal claims, policy recommendations, or statistical power estimates are offered.
• The app does not use a neural network, machine-learning inference API, automated demographic inference, or real personal data.

Privacy and validation

• Processing and storage take place solely in the user's browser. No network requests, analytics, trackers, fonts or CDN libraries are used.
• Local browser storage can be disabled in restricted environments. Export JSON to retain work independently.
• JSON imports are restricted to version 1, 1–500 records, unique safe ASCII identifiers (2–32 characters), valid groups, 0–100 integer scores, exact binary labels, boolean archive values, bounded thresholds and costs.
• Stored and imported text is HTML escaped before rendering. CSV export quotes values and neutralizes common spreadsheet-formula prefixes.
• Archive status is reversible; the Reset control can restore demonstration data after confirmation.

Repository contents

• README.md: Hugging Face configuration, overview, methodology, and limitations.
• index.html: complete responsive application with all CSS and JavaScript bundled locally.
• LICENSE: MIT license.