Skip to content

Local vPIC decoder with reviewed rule fixes - #28

Merged
keptlive merged 1 commit into
mainfrom
local-decode
Nov 18, 2026
Merged

keptlive merged 1 commit into
mainfrom
local-decode

Conversation

@keptlive

Copy link
Copy Markdown
Owner

What this does

Decodes VINs with mcp.vin's own copy of NHTSA's vPIC decode (release 2026_11) instead of NHTSA's live API, and fixes NHTSA's rule rows where they are wrong. Do not merge or deploy without the owner's go. The dataset is not in git: deploy steps are below.

  • Interpreter (lib/vpic-local.mjs): reproduces spvindecode, spvindecode_core and spvindecode_errorcode. It returns the live API's 154-key shape and runs in about 4.4 ms per VIN on the phone.

  • Dataset (scripts/import-vpic.py): builds data/vpic.db from NHTSA's monthly dump (96.5 MB, 17.6 MB as xz). The build stops if NHTSA changes its decode functions.

  • Local first, live fallback (lib/nhtsa.mjs): the live API is used when:

    • the dataset is missing or unreadable;
    • the local decode failed;
    • the WMI is unknown;
    • no model decoded;
    • the model year is newer than the release.

    decode_source names the source, the release and the fallback reason. Batch decodes send only the VINs that need the live API.

  • Rule fixes (data-src/vpic-rule-fixes.jsonl): 26 reviewed fixes with 34 row edits, covering the 33 confirmed errors outside seats and GVWR.

    • Kinds: wrong value 12, narrower key 10, wrong row 2, missing rule 2.
    • An entry is applied only when NHTSA's rows are unchanged. Otherwise the build reports it for review.
    • Reports show the fixed value as corrected (basis mcp_vin_rule_fix), with NHTSA's official value, the reason and the evidence. raw_nhtsa stays official.
    • docs/vpic-rule-fixes.md is the readable diff and can serve as the error report for NHTSA.
  • Accent fix: a test-vehicle fill does not assert a transmission or speeds when EPA lists both manual and automatic. An owner-stated transmission still fills.

  • Monthly refresh (scripts/vpic-refresh.sh): runs on the storage server. It has no cron job and does not deploy.

Parity

Check Result
NHTSA's PostgreSQL spvindecode, NHTSA's rules 25,073 / 25,073 VINs agree on every element, for both the file built without fixes and the fixed file read pristine; 0 local failures
Live API (4,073 cached answers, no new calls) 3,449 agree on all keys

The other 624 live-API differences are data or presentation, not the algorithm:

  • case differences in names: 440;
  • order of multi-valued text: 184;
  • plant name: 28;
  • valid-character cache: 4 VINs, where PostgreSQL agrees with us.

Fix checks:

  • NHTSA test vehicles: the fixes change 44 of 2,418. Every changed value agrees with the lab record where the record has the field.
  • Sample of 25,073 VINs: the fixes change 67 of them.

Tests

npm test: 248 / 248 node tests pass, and all Python tests pass. The tests use a 275 KB fixture cut from the release, with NHTSA test vehicles and synthetic VINs only.

Deploy (owner's go only)

  1. Merge this PR. Then file-copy the changed files to the web server, after diffing each one against the server copy (the server holds uncommitted edits).
  2. Copy vpic.db.xz from the storage server (/root/vpic-local/dryrun/2026_11/) to the web server.
    • xz sha256: 175c6f0b…b21ad
    • db sha256: 45e616aa…837fc
  3. Run xz -d on it next to the app, then mv it to data/vpic.db.
  4. Restart the app.
  5. Verify:
    • 1V2BR2CA3JC513174: drive is FWD, corrected.
    • JTNABAAE3PA004901: transmission is manual, corrected.
    • a 2027 VIN uses the live API, with model_year_newer_than_release.
  6. Rollback: remove data/vpic.db. Decoding then falls back to the live API.

🤖 Generated with Claude Code

Decode VINs with mcp.vin's own copy of NHTSA's vPIC decode (release 2026_11) instead
of the live API, and fix NHTSA's rule rows where they are wrong.

- scripts/import-vpic.py: read the monthly vPIC PostgreSQL dump without a database
  server and write data/vpic.db (96.5 MB); stop when NHTSA's decode functions change.
- lib/vpic-local.mjs: a faithful interpreter of spvindecode. On NHTSA's pristine
  rules it agrees with spvindecode on every element of 25,073 of 25,073 VINs.
- lib/nhtsa.mjs: decode locally first; fall back to the live API when the WMI or
  model is unknown, the model year is newer than the release, or the dataset is
  missing. decode_source names the source, release and fallback reason.
- data-src/vpic-rule-fixes.jsonl: 26 reviewed rule fixes (34 row edits) for the 33
  confirmed decode errors outside seats and GVWR. The build applies an entry only
  when NHTSA's rows are unchanged; otherwise it reports it for review. Fixed values
  are marked corrected (basis mcp_vin_rule_fix) with NHTSA's official value, the
  reason and the evidence. docs/vpic-rule-fixes.md is the readable diff.
- Accent fix: a test-vehicle fill no longer asserts the transmission or speeds
  when EPA lists both manual and automatic for the model and year.
- scripts/vpic-refresh.sh: monthly refresh on the storage server (build, fix check,
  parity with spvindecode, diff, xz). It has no cron job and does not deploy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@keptlive
keptlive merged commit 3d8162e into main Nov 18, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant