Add final project documentation and portfolio package

README.md

@@ -0,0 +1,132 @@
+# InspectIQ
+
+InspectIQ is a reproducible, advisory decision-support project that ranks a supplied OSHA inspection candidate batch for human review using historically validated, leakage-safe features.
+
+## Problem and decision-support framing
+
+Review capacity is limited. InspectIQ orders only the supplied candidates so reviewers can focus a fixed review budget; it does **not** create a complete workplace-risk registry, confirm violations, or initiate enforcement. Every recommendation remains subject to human review and documented override.
+
+## Key verified results
+
+All performance figures below are retrospective results on the labelled **2022 validation period** (600 rows, 154 positives), not claims about the unlabelled 2023 candidate batch.
+
+| Measure | 2022 baseline | Selected Random Forest | Interpretation |
+| --- | ---: | ---: | --- |
+| Positives captured at top 10% | 19 / 60 | 36 / 60 | 17 additional validation positives at the same review budget |
+| Precision@10% | 0.3167 | 0.6000 | Share of reviewed 2022 validation rows labelled positive |
+| Recall@10% | 0.1234 | 0.2338 | Share of 2022 validation positives captured |
+| Lift@10% | 1.2338× | 2.3377× | Ranking concentration relative to the 2022 base rate |
+| PR-AUC | 0.3076 | 0.5236 | Validation ranking quality |
+| ROC-AUC | 0.5873 | 0.7236 | Validation discrimination summary |
+
+The 2023 batch contains 300 supplied candidates with no outcomes loaded by this workflow. Its uncalibrated model outputs are advisory ranking scores, **not calibrated probabilities** and not a current-performance claim.
+
+## Dashboard overview
+
+The Streamlit dashboard provides Review Queue, Candidate Detail, Model Evidence, Monitoring & Governance, and Data & Limitations pages. It supports review-budget filtering, deterministic candidate explanations, evidence display, monitoring summaries, and governance-template downloads. It never silently regenerates artifacts or contacts external APIs on startup.
+
+## System architecture
+
+The pipeline uses cached Day 0 acquisition, a validated labelled foundation, chronological splits, historical features, model comparison, calibration study, local MLflow tracking, deterministic batch ranking, review templates, monitoring, and release checks. See [architecture](docs/architecture.md) for diagrams and lineage.
+
+## Data and label construction
+
+The source is the U.S. Department of Labor OSHA inspection and violation endpoints. California inspections use `activity_nr` as the join key and `open_date` as the candidate date. A positive label means at least one non-deleted Serious, Willful, or Repeat violation. Deleted rows are excluded; incomplete or unknown violation retrieval remains excluded rather than becoming a negative label.
+
+The immutable foundation snapshot is `edbd4bd813ed8e1dbaba9e1c`. It contains 2,100 complete labels: 552 positive and 1,548 negative (26.29% positive); 900 unknown outcomes are excluded. See [data card](docs/data_card.md).
+
+## Chronological evaluation design
+
+Training uses 2020–2021 (1,200 labelled rows), validation uses 2022 (600 labelled rows), and the locked 2023 candidate period contains 300 rows without a target. Information flows forward only. The candidate period is not used for training, calibration, or reported performance.
+
+## Leakage-safe feature engineering
+
+Feature version `day2-historical-v1` uses strictly prior history: a row cannot contribute to its own feature, same-day rows cannot affect one another, validation uses training history only, and candidates use training-plus-validation history only. Industry history is retained; establishment history is omitted because no defensible establishment identifier is available.
+
+## Baseline versus selected model
+
+The baseline uses training-period industry rates with deterministic fallbacks. Eight candidate models were compared on the 2022 validation set; `exp_05_random_forest` was selected by Recall@10%, then precision, lift, PR-AUC, Brier score, and model simplicity. Its Random Forest uses 200 trees, depth 8, minimum leaf size 5, and random state 42.
+
+## Calibration decision
+
+Uncalibrated, sigmoid, and isotonic methods were studied using 2020 base training, 2021 calibration, and 2022 validation. Neither calibrated method meaningfully improved probability quality while preserving ranking utility, so the final package is uncalibrated. Scores must be interpreted as model ranking outputs, not confirmed probabilities.
+
+## MLflow experiment tracking
+
+Local SQLite MLflow records eight Day 3 model experiments and three Day 4 calibration-study runs. A second execution reused all 11 deterministic logical runs. No remote tracker, secret, or DagsHub service is required.
+
+## Batch scoring and human review
+
+The frozen 2023 candidate batch has 300 ranked rows: top 5% = 15, top 10% = 30, and top 20% = 60. The dashboard and governance worksheets support human rationale, override, and escalation fields. No automatic enforcement occurs.
+
+## Monitoring and governance
+
+Monitoring compares the 2023 candidate feature population to 2022 validation (primary) and 2020–2021 training (secondary). The monitoring pipeline is PASS and operational health is WARNING: two cumulative-history features retain raw critical drift but are operational warnings due to expected temporal accumulation. Score drift is not performance drift; complete future outcome labels are needed for performance and outcome-fairness evaluation. Details: [governance](docs/governance.md).
+
+## Repository structure
+
+```text
+app/                 Streamlit review dashboard
+config/              Versioned pipeline and release configuration
+docs/                Architecture, cards, governance, and portfolio material
+reports/             Committed validation summaries and schemas
+src/                 Pipeline, monitoring, governance, and release checks
+tests/               Synthetic and offline unit tests
+run_*.py             Explicit pipeline commands
+```
+
+## Local setup
+
+PowerShell:
+
+```powershell
+py -3.13 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+```
+
+Platform-neutral:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -r requirements.txt
+```
+
+## Running the pipeline
+
+Run commands only when intentionally reproducing the workflow; they can change generated, ignored artifacts. The exact order and network/offline behaviour are documented in [reproducibility](docs/reproducibility.md).
+
+## Running tests and release validation
+
+```powershell
+python -m unittest discover -s tests -t . -v
+python -m compileall app src scripts tests run_release_validation.py
+python run_release_validation.py --mode ci
+python run_release_validation.py --mode local
+```
+
+CI mode is clean-checkout safe and does not require ignored artifacts. Local mode verifies the frozen local model, predictions, and monitoring artifacts without regenerating them.
+
+## Running Streamlit and Docker
+
+```powershell
+python -m streamlit run app/streamlit_app.py
+docker build --tag inspectiq:release .
+docker compose up
+```
+
+The Docker image contains code, configuration, and committed reports only. `docker-compose.yml` mounts locally generated `data`, `artifacts`, and `reports` read-only. Those inputs must exist locally; the container will not download or regenerate them.
+
+## CI behaviour and ignored artifacts
+
+GitHub Actions installs dependencies, checks whitespace, compiles code, runs tests, executes CI-safe release validation, and builds the image without starting the dashboard. Raw data, processed data, model artifacts, predictions, MLflow state, and monitoring artifacts are intentionally ignored: they may be private, large, and reproducible from controlled local inputs. They are not silently committed.
+
+## Limitations and responsible use
+
+Historical OSHA inspections are selection-biased and the California sample is not a census of workplaces or OSHA activity. The early-year acquisition originally required year-balanced sampling; the project does not claim complete national coverage. There are no protected demographic attributes for outcome-fairness evaluation. InspectIQ is advisory-only, requires human review, and must not autonomously trigger inspection or enforcement.
+
+## Future work
+
+With complete future outcomes, evaluate frozen predictions out of time, assess outcome fairness where lawful and appropriate attributes exist, investigate data coverage, and make retraining decisions under documented governance—not from score drift alone.

config/release_config.yaml

@@ -1,12 +1,22 @@
 release_validation_version: day7a-release-v1
 required_source_files:
+  - README.md
   - app/streamlit_app.py
   - src/governance.py
   - src/monitoring.py
   - run_release_validation.py
   - Dockerfile
   - .dockerignore
   - .github/workflows/ci.yml
+required_documentation_files:
+  - docs/architecture.md
+  - docs/model_card.md
+  - docs/data_card.md
+  - docs/reproducibility.md
+  - docs/governance.md
+  - docs/interview_walkthrough.md
+  - docs/resume_material.md
+  - docs/project_metrics.md
 required_config_files:
   - config/dashboard_config.yaml
   - config/monitoring_config.yaml

docs/architecture.md

@@ -0,0 +1,66 @@
+# InspectIQ architecture
+
+## End-to-end flow
+
+```mermaid
+flowchart LR
+  A[Cached OSHA inspections and violations] --> B[Day 0 feasibility]
+  B --> C[Validated labelled snapshot]
+  C --> D[Chronological baseline]
+  C --> E[Historical feature artifacts]
+  E --> F[Day 3 model comparison]
+  F --> G[Day 4 calibration study]
+  G --> H[Local MLflow tracking]
+  G --> I[Deterministic 2023 candidate ranking]
+  I --> J[Streamlit human-review dashboard]
+  I --> K[Monitoring and governance artifacts]
+  K --> J
+  H --> L[Release validation]
+  J --> L
+```
+
+The source snapshot ID identifies the immutable validated foundation; the feature version identifies the feature schema and historical-information contract. Current lineage uses snapshot `edbd4bd813ed8e1dbaba9e1c` and `day2-historical-v1`.
+
+## Chronology and information boundaries
+
+```mermaid
+flowchart LR
+  T[2020 base training] --> U[2021 training and calibration]
+  U --> V[2022 labelled validation]
+  V --> W[2023 locked candidate: no target]
+  T -. prior history only .-> V
+  U -. training plus validation history only .-> W
+  W -. no label, fitting, or evaluation feedback .-> W
+```
+
+Training contains 2020–2021 labels; validation is 2022. The candidate batch is 2023 and has no target column. Strictly-prior feature construction prevents a row, future row, or same-day peer from leaking target information into its features.
+
+## Selection and lineage
+
+The baseline uses training-period industry rates with deterministic fallback. Eight Day 3 candidates are evaluated on 2022 validation; `exp_05_random_forest` is selected. Day 4 compares uncalibrated, sigmoid, and isotonic study artifacts. The final selected package remains uncalibrated because no calibrator qualified under the probability-quality and ranking policy.
+
+MLflow uses a local SQLite store and deterministic logical keys: 8 Day 3 runs plus 3 Day 4 runs are reusable. Batch scoring reads the selected final candidate, generates immutable ranked and top-budget CSVs, and records hashes. It neither refits nor accesses candidate outcomes.
+
+## Dashboard runtime contract
+
+```mermaid
+flowchart TB
+  Image[Docker image: app, src, config, committed reports] --> App[Streamlit dashboard]
+  Data[Host data mount: read-only] --> App
+  Artifacts[Host artifacts mount: read-only] --> App
+  Reports[Host reports mount: read-only] --> App
+  App --> Review[Human review, rationale, override]
+  App --> Evidence[Historical evidence and monitoring]
+```
+
+The dashboard consumes existing artifacts and reports. It never retrieves data, starts a training job, recalibrates, or regenerates candidates at startup. Missing required mounted artifacts produce an actionable validation error.
+
+## Monitoring and release architecture
+
+Monitoring compares 2023 candidate features with 2022 validation (primary reference) and 2020–2021 training (secondary reference). Data drift and score-distribution drift are descriptive; neither proves current performance drift without outcomes. Governance outputs include review and future-outcome templates, with hashes for auditability.
+
+`run_release_validation.py --mode ci` checks source, configuration, committed reports, imports, workflow, Docker contract, documentation, and safety without local artifacts. `--mode local` additionally verifies frozen artifact paths, hashes, counts, and governance templates. The Docker image intentionally excludes raw/processed data, MLflow state, models, predictions, and monitoring artifacts; Compose mounts them read-only for local runtime.
+
+## Safety boundaries
+
+InspectIQ is candidate ranking for human review. It does not assert a violation, provide a calibrated probability, join 2023 labels, calculate current performance or outcome fairness, deploy an enforcement service, or automatically trigger enforcement.

docs/data_card.md

@@ -0,0 +1,29 @@
+# Data card
+
+## Dataset summary and scope
+
+InspectIQ uses 3,000 retrieved California OSHA inspections across 2020–2024 for feasibility and data-foundation work. Complete inspection-level labels are available for 2,100 rows: 552 positive and 1,548 negative. The remaining 900 outcomes are unknown and excluded. This is not a sample of every California workplace or all OSHA activity.
+
+## Source endpoints and entity
+
+The source is the U.S. Department of Labor OSHA inspection and violation endpoints. The inspection entity is `activity_nr`; violation records join through the same key. `open_date` determines chronology.
+
+## Sampling, coverage, and early-year limitation
+
+The default feasibility selection is year-balanced across the requested period, targeting approximately equal rows per calendar year where data exists. Earlier downloader behaviour could concentrate a bounded chronological fetch in the earliest dates; the current selection strategy addresses this by retrieving years separately and retaining deterministic chronological order. It remains a bounded, California-only operational sample rather than population coverage.
+
+## Label construction and quality controls
+
+A row is positive when it has at least one non-deleted Serious, Willful, or Repeat violation. Deleted violation rows are excluded. Missing/incomplete outcome retrieval and unknown violation types are safely excluded rather than labelled negative. Validation checks include identifier uniqueness, required columns, valid dates, categorical handling, and manifest/hash integrity.
+
+## Chronology, fields, and leakage
+
+Complete labels are split into 2020–2021 training (1,200), 2022 validation (600), and a 2023 candidate period (300) that has no target in the workflow. Candidate dates and `activity_nr` are excluded from model features. Retained features include inspection descriptors, establishment-size proxy, open month, and prior industry counts/rates/status. Establishment history is omitted because no defensible key is available.
+
+## Bias, privacy, storage, and use
+
+Historical inspection data reflects prior inspection and recording processes, so selection bias remains. The project has no protected demographic attributes for outcome-fairness evaluation. Generated raw/processed data and artifacts are ignored from Git to limit accidental sharing and keep large, reproducible operational state out of source control. Appropriate use is advisory candidate prioritization with review; inappropriate use includes asserting liability, autonomous enforcement, or generalizing to every workplace.
+
+## Reproducibility and caching
+
+Day 0 caches are manifest-backed and resumable. Compatible inspection snapshots and completed violation batches are reused; incomplete retrieval remains unknown. Reproduction commands and their network behaviour appear in [reproducibility](reproducibility.md).

docs/governance.md

@@ -0,0 +1,25 @@
+# Governance summary
+
+## Advisory-only purpose
+
+InspectIQ ranks supplied candidates for human review. It does not establish a violation, create an enforcement target, or automatically initiate inspection or enforcement.
+
+## Human-review workflow
+
+Reviewers receive an advisory score, rank, explanations, and historical evidence. They record status, decision, reasoning, notes, review time, override, and escalation requirement. A reviewer may override model priority; model output is not a mandate.
+
+## Unknown outcomes and frozen predictions
+
+Incomplete outcome retrieval remains unknown rather than negative. The 2023 candidate batch is frozen and unlabelled in this workflow. Future outcome evaluation must join complete labels under a new, auditable process; frozen prediction artifacts and hashes protect against silent reranking.
+
+## Monitoring and incident response
+
+Pipeline `PASS` means the monitoring computation completed its configured integrity checks. Operational health is separately `HEALTHY`, `WARNING`, or `CRITICAL`. A `WARNING` can reflect expected temporal accumulation or score-distribution change and is not a current performance claim. Data drift measures feature/population change; score drift measures output distribution change; performance drift needs complete outcome labels.
+
+Review-exposure diagnostics are descriptive and do not prove discrimination. No protected demographic attributes are available for outcome-fairness analysis. Monitoring artifacts, templates, and ranking outputs carry hashes for auditability.
+
+## Retraining and operational stop conditions
+
+Retraining should follow a documented review of data quality, outcome completeness, population change, validation evidence, and operational harms—not a single drift metric. Stop or restrict use when artifact integrity fails, required review controls are unavailable, inputs are out of contract, monitoring is critical without a documented disposition, or an operator proposes autonomous enforcement.
+
+This document is governance guidance, not legal or compliance certification.