ConductWatch is an explainable consumer-complaint intelligence project for banking conduct teams. It turns the CFPB Consumer Complaint Database into a working analyst website: weekly change detection, readable evidence, geographic context, recurring language, and an issue-triage model in one place.
The project began with a practical question: how can a large public complaint archive become useful without pretending that every statistical change proves misconduct? ConductWatch keeps that distinction visible. A signal is a prompt to investigate, not a verdict.
- Download the small
complaints_sample.csvincluded in this repository. - Open Analyze CSV.
- Drop the file into the page and explore its timeline, comparison periods, signals, companies, states, and evidence.
The example should produce 956 valid dated rows and five signals to review. The analyzer runs inside the browser. It does not require an account, upload the file to an application server, or retain the result after the tab is closed. It accepts files up to 25 MB and reads at most 50,000 rows to keep the page responsive.
- Live dashboard — select any date range, switch between week, month, and year, compare two independent periods, and inspect historical watchlists.
- Signal review — see observed volume beside a robust expected range, then expand the evidence ledger only when more detail is useful.
- Evidence explorer — search the public complaint examples linked to every current signal.
- Model lab — inspect the time-based evaluation, class results, common confusions, and a local issue-triage demonstration.
- Analyze CSV — test a separate complaint file locally with adaptive baselines, maps, rankings, comparisons, and narrative evidence.
- Methodology — read the formulas, data lineage, assumptions, and limits behind the interface.
The current analytical snapshot was built from an official CFPB bulk archive:
- 16,996,400 source rows and valid complaint rows;
- 0 repeated complaint IDs in the exact partitioned audit;
- 2011-12-01 → 2026-08-09 coverage;
- 3,833,003 published narratives;
- source SHA-256 recorded in
data/manifest.json.
Six model settings were selected on a 27,000-row validation period. The winning Logistic SGD model was then evaluated once on a separate 27,000-row later-time test period:
| Metric | Result |
|---|---|
| Accuracy | 0.7181 |
| Macro-F1 | 0.7136 |
| Weighted-F1 | 0.7136 |
| Top-three accuracy | 0.9635 |
| Log loss | 0.7900 |
The score is reported as measured, not rounded into a marketing claim. Exact issue labels overlap, especially in debt and credit reporting; the model lab shows every class and the important confusions. Top-three accuracy is included because the intended use is analyst triage, not automated adjudication.
Official CFPB ZIP (8.46 GB uncompressed) Census estimates
\ /
streamed validation + SHA-256
↓
local DuckDB (16.99M rows)
↓
robust signals | cleaned NMF topics | model selection by time
↓
compact, privacy-reviewed JSON snapshot
↓
React + TypeScript Sites app
The raw ZIP, DuckDB database, and trained binary stay out of Git. The public site receives full-archive aggregates, 26 weekly signal snapshots, model metrics, explanation terms, and up to 1,200 truncated public evidence examples. Sending all 17 million raw rows to a static browser would be slow and unnecessary; full-row analysis remains reproducible in local DuckDB.
The main stack is Python 3.12, DuckDB, pandas, scikit-learn, React 19, TypeScript, and ChatGPT Sites. Tests cover ingestion and analytical logic, the browser-local CSV engine, production builds, and server rendering for every route.
Requirements: Node.js 22.13+ and Python 3.12.
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
npm ci
# Build from an official CFPB ZIP without extracting it
.\.venv\Scripts\python.exe -m conductwatch.pipeline --input "C:\path\to\complaints.csv.zip" --force
# Start the site
npm run devTo fetch the newest archive and rebuild the complete analytical output later:
.\scripts\refresh-data.ps1Publishing a rebuilt snapshot is intentionally a reviewed step. The repository does not contain a scheduled job that downloads a multi-gigabyte archive or silently redeploys the public site.
.\.venv\Scripts\python.exe -m ruff check src tests scripts
.\.venv\Scripts\python.exe -m pytest
npm run lint
npm testnpm test creates the production Sites build, exercises the CSV analysis engine, and server-renders every public route. The same checks run in GitHub Actions for pushes and pull requests.
app/ pages, browser tools, maps, charts, and visual system
src/conductwatch/ ingestion, validation, analytics, and ML pipeline
public/data/ compact generated snapshot used by the public site
data/examples/ small privacy-reduced CSV for trying the analyzer
models/ committed metrics; ignored trained binary
scripts/ data refresh and example-data utilities
docs/ architecture, project report, data/model cards
tests/ Python, browser-analysis, and route tests
.github/workflows/ repeatable repository checks
.openai/hosting.json ChatGPT Sites project configuration
Start with the project report for the complete story. The architecture, data card, model card, and responsible-AI note document the choices and limits separately.
Complaint volume reflects reporting behavior, awareness, company footprint, product mix, and database coverage. It is not a market incidence rate. Company comparisons need exposure or market-share denominators that this dataset does not provide. ConductWatch should not be used for adverse action, automated enforcement, or legal conclusions.
The project is independent and is not endorsed by the CFPB. The code is released under the MIT License; public source data keeps its own terms and attribution. See the data and attribution notice for the distinction. Contributions are welcome under the practical guidelines in CONTRIBUTING.md.
Built by Mazen Ashraf · GitHub · Email