README.md

---
title: Fintech Dark Patterns Detector
emoji: 🛡️
colorFrom: blue
colorTo: gray
sdk: docker
app_port: 8000
pinned: false
---

# Dark Pattern NLP Detector

This project detects potentially manipulative language in fintech interfaces.
It supports screenshot auditing through OCR, direct text classification, model
evaluation, dataset exploration, and a Chrome Manifest V3 extension.

## NLP pipeline

1. Screenshot text is extracted with Tesseract OCR. Low-confidence OCR words are
   discarded before classification.
2. Text is represented using word TF-IDF n-grams `(1, 3)` and character
   `char_wb` n-grams `(3, 5)`.
3. A class-balanced Logistic Regression model predicts one of seven dark
   pattern classes or `Not Dark Pattern`.
4. Sigmoid calibration converts raw model scores into better-behaved confidence
   estimates.
5. Word-level linear contributions provide an explanation for each prediction.

Evaluation uses a grouped held-out fold based on `page_id`. This prevents text
from the same source page appearing in both training and testing.

## Run locally

```powershell
npm install
npm run build
cd ai-backend
python server.py
```

Open `http://127.0.0.1:8000`.

Tesseract OCR must be installed. On Windows, the backend automatically checks
`C:\Program Files\Tesseract-OCR\tesseract.exe`.

## Test

```powershell
npm run test:backend
npm run check:extension
npm run build
```

The backend tests cover grouped evaluation, calibrated text classification,
batch IDs, remote-image blocking, and the screenshot OCR response.

## Chrome extension

The ready-to-load extension is in [`extension`](./extension). Start the local
API, open `chrome://extensions`, enable Developer mode, choose **Load unpacked**,
and select the `extension` directory itself. The selected directory must contain
`manifest.json` at its top level; do not select the ZIP or the `space` directory.

Generate both a ZIP and a Chrome-ready unpacked artifact with:

```powershell
npm run package:extension
```

For the least ambiguous installation path, select
`artifacts\dark-pattern-nlp-auditor-unpacked` in Chrome after running that
command.

The extension reads visible DOM text only after the user clicks it. It sends one
batch request to the configured local API, highlights flagged elements, and
shows results in Chrome's side panel.

## Known limitations

- `Forced Action`, `Sneaking`, and `Obstruction` have fewer than 100 labeled
  examples, so their class-level metrics remain unreliable.
- OCR cannot perfectly recover text from low-resolution or highly stylized UI.
- Closed shadow roots, cross-origin frames, canvas, and image-only web content
  are not available to the extension's DOM scanner.
- Compliance descriptions are screening guidance, not legal conclusions.