# Project 05 — Customer & Operational Intelligence

Independent capability demonstration by ONE Light Analytics. Public complaint records connect reported customer issues with operational handoffs and recorded company response. This is not a client engagement or a causal explanation of service failures.

## Source

Consumer Financial Protection Bureau, Consumer Complaint Database:
https://www.consumerfinance.gov/data-research/consumer-complaints/

Field definitions: https://cfpb.github.io/api/ccdb/fields.html

The CFPB states its published complaint data are freely available for use, analysis and building on. The public database is not a statistical sample of consumers' experiences. Company size, customer exposure and reporting behaviour affect complaint counts.

Exact API query and downloaded CSV SHA-256 appear in `validation.json`. Frozen retrieval: 9 October 2026. The filter requests checking-or-savings complaints from 1 January to 1 April 2025. The returned export includes 1 April, so a strict retained-receipt-date filter keeps 1 January through 31 March inclusive. This removes 202 of 29,091 source records and retains 28,889.

`source-snapshot.csv.gz` preserves the exact official API CSV used for this study, including its public source metadata. The browser model excludes company names, state, ZIP, demographic tags, complaint identifiers and any free text. No individual records are displayed. Later live API extracts may differ as records are updated.

## Reproduce the frozen snapshot

Python 3.11+ and Node are sufficient; no third-party Python dependencies or API key is required. Run from the website repository root:

```sh
python projects/customer-operations/build.py --source-gzip projects/customer-operations/source-snapshot.csv.gz
node projects/customer-operations/test-model.mjs
```

To use a separately downloaded official CSV:

```sh
python projects/customer-operations/build.py --source-csv /absolute/path/to/source.csv
```

Running `build.py` without arguments downloads a fresh API extract. Treat any changed source hash as a new snapshot and reassess the published findings and fixed test controls before replacing the study.

## Measures and denominators

| Measure | Definition | Limit |
| --- | --- | --- |
| Complaint volume | Count of retained complaint IDs | Not a population complaint rate |
| Timely response share | Yes / (Yes + No) in source flag | Not satisfaction or exact response duration |
| Non-timely flags | Timely response? = No | Distinct from response-category text |
| Recorded closure with relief | Monetary + non-monetary relief categories / all selected records | Not confirmed resolution or quantified financial relief |
| Forwarding interval | UTC Date sent to company minus Date received, in elapsed hours | Not company response or resolution duration |
| Above-24-hour forwarding | Valid forwarding intervals >24 hours | Illustrative review boundary, not an official SLA |
| Exception share | Group non-timely flags / all selected non-timely flags | Unavailable if the denominator is zero |

Medians are recomputed from the selected record-level intervals, not averages of group medians. Unknown timeliness is excluded from the rate denominator and retained in record totals. Missing or negative forwarding durations are excluded only from duration measures. No such values occur in this frozen cohort. Unique complaint IDs are validated before the browser model removes identifiers. No category-level count is silently deleted.

## Controls

28,889 records = 28,794 Yes + 95 No. Recorded responses: 25,738 explanation; 2,141 monetary relief; 994 non-monetary relief; 16 untimely-response category. Receipt months: January 18,367; February 5,452; March 5,070. Median forwarding 0.2388888889 hours; 1,878 intervals exceed 24 hours.

The browser's four filters apply consistently to every card, table, chart and export. The priority table's editable minimum group size (default 50) affects eligibility and display of comparison rates, not the headline cohort. Small groups remain in the totals and excluded-priority counts are displayed. The minimum is a proposed review aid, not a significance test. The channel table suppresses rates when the known-status denominator is below that minimum. Overall small scopes retain counts with a visible instability warning.

## Evidence boundaries

Reported issues are consumer-selected categories, not verified causes. Company response categories are not consumer satisfaction. The fields do not provide closure timestamps, repeat contacts, churn, revenue impact or verified resolution. Channel differences are unadjusted descriptions and may reflect case mix. Monthly variation is not attributed to company action or demand without additional evidence. Do not compare providers or markets using these counts as though customer populations were equal.

## Outputs

- Interactive case study and consistent-scope issue export.
- Frozen public-source archive, portable browser data model and source-to-model build script.
- Full-cohort issue summary, validation controls and meaningful model tests.
- Management brief and an improvement measurement framework.

The dashboard runs as a static website. Native CRM connections and an internal case-review study would require client-specific access and target-workflow validation; neither is represented as completed here.