132 lines
5.8 KiB
Markdown
132 lines
5.8 KiB
Markdown
# Summer Project 2026
|
|
|
|
kevinBell@Linux.com
|
|
|
|
https://kevinbell.dev/
|
|
|
|
Kevin Bell's summer 2026 data project using state of Utah county vehicle-registration
|
|
and emissions-inspection data.
|
|
|
|
See the [data inventory](docs/data_inventory.md) and the data-backed
|
|
[project shortlist](docs/project_options.md).
|
|
|
|
## Selected project
|
|
|
|
The selected direction is **Utah Vehicle Health**, an explainable model and
|
|
dashboard for the first-attempt outcome of a vehicle's next inspection episode.
|
|
Start with the [project charter](docs/project_charter.md), then use the
|
|
[modeling protocol](docs/modeling_protocol.md) and
|
|
[dashboard specification](docs/dashboard_spec.md) as the project contracts.
|
|
The latest private-sample pipeline findings are summarized in
|
|
[development results](docs/development_results.md), with intended use and
|
|
limitations consolidated in the [model card](docs/model_card.md).
|
|
|
|
## Safe database access in VS Code
|
|
|
|
The local `.env` file contains the standard PostgreSQL connection variables and
|
|
is intentionally excluded from Git. Never put those values in source code,
|
|
screenshots, browser JavaScript, or a Bolt project.
|
|
|
|
1. Install the workspace-recommended **PostgreSQL** extension by Microsoft
|
|
(`ms-ossdata.vscode-pgsql`).
|
|
2. In VS Code, run **Tasks: Run Task** and choose
|
|
**Countydata: test read-only connection**. It loads `.env`, requires TLS, and
|
|
forces the PostgreSQL session into read-only mode.
|
|
3. To browse the server visually, open the PostgreSQL sidebar and add a
|
|
connection using the values in `.env`. Set SSL mode to **Require**, save the
|
|
profile at **User** scope, and store the password in macOS Keychain rather
|
|
than workspace settings.
|
|
4. Connect to `countydata` and run [sql/00_read_only_connection_check.sql](sql/00_read_only_connection_check.sql).
|
|
Safe aggregate examples are in [sql/01_safe_data_overview.sql](sql/01_safe_data_overview.sql).
|
|
|
|
The selected project's first aggregate cohort check is
|
|
[sql/10_episode_cohort_feasibility.sql](sql/10_episode_cohort_feasibility.sql).
|
|
Private bounded extraction is handled by
|
|
[scripts/export_inspection_batch.py](scripts/export_inspection_batch.py); it
|
|
requires the project-specific `VIN_HASH_KEY` described in `.env.example` and
|
|
never writes a raw VIN.
|
|
|
|
The current database login has write privileges even though this project only
|
|
needs reads. Ask the database administrator for a dedicated read-only role
|
|
before connecting any deployed service. Until then, always use explicit
|
|
read-only transactions.
|
|
|
|
## Reproducible development workflow
|
|
|
|
Create the local environment once:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
.venv/bin/pip install -r requirements.txt
|
|
.venv/bin/python scripts/create_vin_hash_key.py
|
|
```
|
|
|
|
The recommended way to run the pipeline is **Tasks: Run Task** in VS Code. The
|
|
tasks preserve the intended order:
|
|
|
|
1. Test the read-only TLS connection.
|
|
2. Run the source outcome-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 every test.
|
|
6. Train the baselines while leaving the 2025 test partition locked.
|
|
7. Train the nonlinear comparison while leaving the same partition locked.
|
|
|
|
The development history sample is deliberately not population-representative.
|
|
It exists to exercise feature engineering and modeling before a complete,
|
|
contiguous bounded extraction is approved. Generated extracts, marts, database
|
|
files, keys, and model artifacts remain under Git-ignored private paths.
|
|
|
|
The 2025 metrics are not calculated by the normal training task. Unlocking them
|
|
requires the conspicuous `--evaluate-locked` flag after the feature set,
|
|
hyperparameters, calibration method, and reporting plan are frozen.
|
|
That gate was opened once on the page-sampled development extract during live
|
|
verification; the normal artifact paths were then regenerated closed. The
|
|
audit trail is in [development results](docs/development_results.md), and no
|
|
further 2025-informed tuning is permitted.
|
|
|
|
## Sanitized dashboard preview
|
|
|
|
After training both closed model bundles, run **Tasks: Run Task** and choose
|
|
**Utah Vehicle Health: export sanitized dashboard preview**. The exporter
|
|
publishes only suppression-reviewed JSON under `dashboard/public/data`; it
|
|
refuses the sampled mart unless the explicit development-preview flag is used
|
|
and refuses model artifacts containing holdout metrics.
|
|
|
|
Preview the site without exposing the repository root:
|
|
|
|
```bash
|
|
node dashboard/server.mjs
|
|
```
|
|
|
|
Then open `http://localhost:4173`. Do not serve the repository root, because it
|
|
contains the local connection profile and private ignored directories.
|
|
|
|
The checked-in bundle is visibly labeled as a non-population development
|
|
preview. Before a real public-data release, rerun the frozen pipeline on an
|
|
approved complete extraction and pass the publication review documented in
|
|
[the dashboard specification](docs/dashboard_spec.md).
|
|
|
|
Local and Bolt handoff instructions are in
|
|
[dashboard/README.md](dashboard/README.md). Bolt can import a GitHub repository,
|
|
but the hosted site root must be the `dashboard` directory; never copy `.env`,
|
|
private data, model artifacts, or database tooling into a web project.
|
|
|
|
## Data safety and publishing
|
|
|
|
The source contains direct identifiers and operational data, including VINs,
|
|
plates, user records, sessions, and upload metadata. A public dashboard should
|
|
contain only de-identified aggregates and model outputs with minimum group-size
|
|
suppression.
|
|
|
|
Recommended deployment flow:
|
|
|
|
```text
|
|
countydata (read-only) -> local ETL/modeling -> sanitized aggregate tables/files
|
|
-> Bolt-hosted dashboard
|
|
```
|
|
|
|
Do not connect a browser directly to `countydata`. If the dashboard must refresh
|
|
automatically, use a scheduled backend job with a dedicated read-only database
|
|
role and copy only approved aggregate results into the hosted application.
|