Centralized_I-M_Database/SummerProject2026
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

repository is now a presentation-ready development prototype

Browse Source
This commit is contained in:
kevinbell
2026-07-21 15:40:44 -06:00
parent 640165649d
commit 88161a6f16
24 changed files with 1989 additions and 946 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+121 -93
View File
@@ -1,61 +1,57 @@
# Summer Project 2026
# Utah Vehicle Health
kevinBell@Linux.com
Kevin Bell's summer 2026 development prototype for the first-attempt outcome of
a returning vehicle's next emissions-inspection episode.
https://kevinbell.dev/
## Prototype status
Kevin Bell's summer 2026 data project using state of Utah county vehicle-registration
and emissions-inspection data.
The repository implements one research question:
See the [data inventory](docs/data_inventory.md) and the data-backed
[project shortlist](docs/project_options.md).
> 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?
## Selected project
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.
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).
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.
## Safe database access in VS Code
Start with the [final report](docs/final_report.md). Supporting deliverables:
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.
- [Project charter](docs/project_charter.md)
- [Leakage-safe modeling protocol](docs/modeling_protocol.md)
- [Detailed development results](docs/development_results.md)
- [Model card](docs/model_card.md)
- [Static dashboard specification](docs/dashboard_spec.md)
- [Private-to-public architecture](docs/architecture.mmd)
- [10-minute presentation outline](docs/presentation_outline.md)
- [Dashboard demo script](docs/demo_script.md)
- [Dashboard-only Bolt deployment](docs/bolt_deployment.md)
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).
5. To inspect every visible database, relation, column, and a bounded sample of
raw JSON field paths without printing row values, run **Countydata: inventory
metadata safely**. The task uses [scripts/inventory_metadata.py](scripts/inventory_metadata.py)
and enforces the same TLS and read-only requirements.
The [data inventory](docs/data_inventory.md) and archived
[project options](docs/project_options.md) provide source-discovery history;
they do not expand the finished prototype scope.
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.
## Privacy boundary
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.
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`.
## Reproducible development workflow
```text
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:
@@ -65,71 +61,103 @@ python3 -m venv .venv
.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:
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, presentation materials, or a Bolt project.
## 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](sql/00_read_only_connection_check.sql)
after connecting. Safe aggregate examples are in
[sql/01_safe_data_overview.sql](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](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 the source outcome-mapping and aggregate feasibility audits.
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 every test.
6. Train the baselines while leaving the 2025 test partition locked.
7. Train the nonlinear comparison while leaving the same partition locked.
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 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 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 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.
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.
## Sanitized dashboard preview
## Tests
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.
Run the complete repository test suite:
Preview the site without exposing the repository root:
```bash
.venv/bin/python -m unittest discover -s tests -v
```
Run the dashboard contract checks directly:
```bash
npm --prefix dashboard test
```
## Static dashboard
Preview the site from 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.
Open `http://127.0.0.1:4173`. Do not open `index.html` with a `file:` URL and do
not serve the repository root.
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).
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.
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.
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.
## Data safety and publishing
## Publish through Bolt
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.
Do **not** import this full source repository into Bolt. Create a separate
deployment project or repository containing only the contents of `dashboard/`,
so `index.html` is at that project's root. Do not copy `.env`, private data,
artifacts, models, SQL, pipeline scripts, credentials, or unrelated repository
history.
Recommended deployment flow:
Follow the complete preflight, import, Bolt Hosting, and post-publication checks
in [docs/bolt_deployment.md](docs/bolt_deployment.md). No publishing action is
performed by this repository.
```text
countydata (read-only) -> local ETL/modeling -> sanitized aggregate tables/files
-> Bolt-hosted dashboard
```
## Author
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.
Kevin Bell
<kevinBell@Linux.com>
<https://kevinbell.dev/>