Utah Vehicle Health

Kevin Bell's summer 2026 development prototype for the first-attempt outcome of a returning vehicle's next emissions-inspection episode.

Prototype status

The repository implements one research question:

Using only information available before an inspection episode begins, how well can a calibrated logistic regression estimate whether a returning vehicle's next episode will have a first-attempt non-pass outcome?

The final model is regularized logistic regression with Platt calibration. Histogram gradient boosting is a benchmark only. The final feature set uses inspection history; DMV enrichment, multiclass modeling, cold-start prediction, station analysis, and vehicle-level prediction service are outside scope.

All analytical results and dashboard values come from the private, page-sampled 10,000-vehicle development cohort. They are sample results, not population estimates. They must not be used for statewide/county prevalence, county rankings, causal claims, individual decisions, diagnoses, or guarantees.

Start with the final report. Supporting deliverables:

• Project charter
• Leakage-safe modeling protocol
• Detailed development results
• Model card
• Static dashboard specification
• Private-to-public architecture
• 10-minute presentation outline
• Dashboard demo script

The data inventory and archived project options provide source-discovery history; they do not expand the finished prototype scope.

Privacy boundary

Never publish or display VINs, plates, ZIPs, stations, technician identifiers, private vehicle tokens, raw JSON, credentials, operational records, or row-level predictions. Private extracts, marts, databases, keys, and model artifacts stay in Git-ignored local paths. The browser never connects to countydata.

countydata (read-only)
    -> private local extraction, feature, and model pipeline
    -> suppression-reviewed aggregate JSON
    -> dashboard-only static site

Local setup

Create the local environment once:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python scripts/create_vin_hash_key.py

The local .env contains PostgreSQL connection values and the project-specific VIN_HASH_KEY; it is excluded from Git. Never put those values in source code, screenshots, browser JavaScript, or presentation materials.

Safe database access in VS Code

1. Install the workspace-recommended Microsoft PostgreSQL extension (ms-ossdata.vscode-pgsql).
2. Run Tasks: Run Task > Countydata: test read-only connection. The task requires TLS and forces the PostgreSQL session into read-only mode.
3. If using the PostgreSQL sidebar, store the profile at User scope and the password in macOS Keychain, not workspace settings.
4. Run sql/00_read_only_connection_check.sql after connecting. Safe aggregate examples are in sql/01_safe_data_overview.sql.
5. Run Countydata: inventory metadata safely to inspect relation/field metadata without printing row values. The task uses scripts/inventory_metadata.py.

The current database login has broader privileges than this project needs. Continue to enforce read-only transactions and use a dedicated read-only role before any separately approved operational integration.

Reproducible private workflow

The VS Code tasks preserve the intended order:

1. Test the read-only TLS connection.
2. Run label-mapping and aggregate feasibility audits.
3. Export the private 10,000-vehicle development histories.
4. Build the private DuckDB warehouse and Parquet feature mart.
5. Run the test suite.
6. Train the baselines and logistic model with the 2025 gate closed.
7. Train the boosted-tree benchmark with the same gate closed.
8. Export the sanitized dashboard preview from approved pre-2025 partitions.

The extraction is deliberately not population-representative. It page-samples inspection records and then retrieves complete histories for the selected vehicles, which over-represents vehicles with more inspection records.

The explicit 2025 gate was opened once after specifications were frozen. No model was changed in response. The values in the final report are one-time development-sample holdout diagnostics—not pristine future-test or population performance. Normal training leaves the gate closed.

Tests

Run the complete repository test suite:

.venv/bin/python -m unittest discover -s tests -v

Run the dashboard contract checks directly:

npm --prefix dashboard test

Static dashboard

Preview the site from the repository root:

node dashboard/server.mjs

Open http://127.0.0.1:4173. Do not open index.html with a file: URL and do not serve the repository root.

The four routes are Overview, Sample cohorts, Model & benchmark, and Data & methods. The site identifies calibrated logistic regression as final, the tree as benchmark-only, and displayed model cards as 2024 calibration-fit checks. The opened 2025 comparison stays in the report and presentation, not the public JSON. There is no vehicle-level prediction service.

The browser validates schemas, publication flags, cross-file consistency, and checksums. It shows no estimates if the approved aggregate bundle fails its contract. Every checked-in asset is marked as a development preview and not a population estimate.

Live demo from another computer

When both computers are on the same network, start the LAN demo from the repository root. Stop any older dashboard process with Ctrl-C first:

node dashboard/server.mjs --lan

The server prints a This computer URL and one or more interface-labeled Other devices URLs. Open the URL for the shared Wi-Fi or Ethernet interface on the second computer; do not use 0.0.0.0 as the browser address. Confirm the header reads Validated sample aggregates. Stop the server with Ctrl-C after the demo.

The LAN page still checks every approved JSON asset against its SHA-256 digest. Browsers do not expose the SubtleCrypto digest API to a non-loopback plain-HTTP page, so the dashboard includes a dependency-free checksum implementation for that case. These checks validate bundle consistency; plain HTTP does not authenticate the network transport, so use a trusted demo network.

Public hosting is not required

The presentation plan is the same-network live demo above. Nothing needs to be uploaded or published, and the server exposes only the dashboard's explicit static-file allowlist. If public hosting is ever reconsidered, publish only a separately reviewed copy of the dashboard/ directory—never the private source repository.

Author

Kevin Bell

kevinBell@Linux.com

https://kevinbell.dev/