VHG (Vehicle Health Governance) — Demo-Only Prototype

This repository is a synthetic, demo-only, non-production reference prototype.

Absolute guardrails (must-read)

• Synthetic VIN keys only: this system accepts VIN keys like SYNTHVIN0001.
  • It rejects real 17-character VIN formats and any non-matching identifiers.
• No external network calls in core logic: all engines operate only on local SQLite state.
• No real OEM / dealer / safety datasets: no Ford datasets, no dealer systems, and no safety usage.
• All thresholds / likelihood ratios are illustrative: values are intentionally synthetic.

What VHG computes

For a given vin_key + subsystem, VHG evaluates evidence and produces:

• Posterior (P): computed via log-odds update using illustrative likelihood ratios (LRs) from present evidence and absence evidence.
• Confidence (C): coverage + corroboration factor, clamped to ([0,1]).
• Staleness (S): maximum age (days) among contributing evidence items at evaluation time.

These feed a governance decision via a fixed threshold matrix (demo-only).

Demo math definition (illustrative)

• Posterior (P):
  • (logit(P) = logit(prior) + \sum_i \ln(LR_i))
  • (P = \sigma(logit(P)))
• Confidence (C):
  • coverage (=\frac{n_{evaluated}}{n_{expected}})
  • corroboration factor:
    • 1.2 if evidence directions agree (non-mixed)
    • 0.7 if mixed
    • else 1.0
  • (C = clamp(coverage \cdot factor, 0, 1))
• Staleness (S):
  • maximum age (days) of contributing manifest items at evaluation time

Governance matrix (demo-only)

• (P \ge 0.85) and (C \ge 0.70) and (S \le 7) → SUPPRESS
• (P \ge 0.85) and (C < 0.70) and (S \le 7) → HOLD_REQUEST_SIGNAL
• (P \ge 0.85) and (C \ge 0.70) and (S > 30) → HOLD_STALE
• (P < 0.40) and (C \ge 0.50) → SUSTAIN
• (P < 0.40) and (C < 0.50) → ESCALATE
• else → MONITOR

Tech stack

• Python 3.11
• FastAPI
• SQLite (vhg.db) via SQLAlchemy 2.x
• Pytest
• CLI scripts (python -m ...)

Repo layout (fixed)

The project lives under vhg-prototype/ and contains the vhg/ package, seed generators, CLI tools, and tests.

Quickstart (demo)

From the vhg-prototype/ directory:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Create synthetic data (writes vhg.db locally):

python -m vhg.seed.generate_synth_data --scenario oil --n_vins 5

Run the API:

./scripts/run_api.sh

If you're running in a remote environment (VM/container/Codespaces), bind externally:

VHG_HOST=0.0.0.0 VHG_PORT=8000 ./scripts/run_api.sh

Open the single-page timeline UI:

• http://127.0.0.1:8000/

Facilitator runbook (live learning session)

Goal: help engineers + PMs understand what changed, why it changed, and what the system did at each step.

Script (15–25 minutes)

1. Start the API and open the UI:

   • Open http://127.0.0.1:8000/

2. Click Guided: oil story (seed + replay + explain).

3. In the table, click 2–3 different dates:

   • A date where absence evidence first appears (you’ll see new ABSENCE items in the Explain panel).
   • A date that shows RETRO recompute (Explain panel still shows the final stored snapshot for that day; the timeline row indicates a late-ingested event triggered recomputation).

4. Use the Explain selected day panel to narrate:

   • Posterior: prior + sum of (\ln(LR)) contributions from present + absence evidence
   • Confidence: coverage (\frac{n_{evaluated}}{n_{expected}}) and corroboration factor
   • Staleness: age of the oldest contributing evidence
   • Governance band: matrix mapping + stored rationale

5. Click Load events + memory and point out:

   • occurred_at vs ingested_at (why “late ingestion” creates retroactive recompute)
   • memory records (how actions are remembered over time)

6. Click Apply decay (pick a later as-of date) to show tier demotion behavior.

7. Click Run recalibration to demonstrate constellation priors updating based on confirmed/contradicted outcomes.

Replay governance for one synthetic VIN key:

python -m vhg.cli.replay --vin SYNTHVIN0001 --subsystem ENGINE_OIL --from 2026-01-01 --to 2026-05-01 --step-days 1

Inspect stored records:

python -m vhg.cli.inspect_vin --vin SYNTHVIN0001

Run tests:

pytest -q

Database

The SQLite database file is local: vhg.db (created on demand). Tables are created automatically on startup (API/CLI/seed), using SQLAlchemy metadata.