feat: Replace NHTSA VIN decode with Google Gemini via OCR service (#223) #229

Merged

egullickson merged 9 commits from issue-223-replace-nhtsa-vin-decode-gemini into main 2026-02-20 03:10:48 +00:00

Conversation 0 Commits 9 Files Changed 43

+804 -538

egullickson commented 2026-02-19 03:53:18 +00:00

Owner

Copy Link

Copy Source

Summary\n\nReplaces the NHTSA vPIC API integration for VIN string decoding with Google Gemini, routed through the Python OCR microservice (mvp-ocr).\n\n### Changes\n- M1 (#224): New POST /decode/vin endpoint on OCR service using GeminiEngine.decode_vin()\n- M2 (#225): VinDecodeResponse type and OcrClient.decodeVin() method (JSON POST)\n- M3 (#226): Rewired VehiclesController to use OcrClient instead of NHTSAClient, moved cache logic to VehiclesService with format-aware reads, renamed nhtsaValue to sourceValue\n- M4 (#227): Deleted vehicles/external/nhtsa/ (3 files), removed VPICVariable/VPICResponse, updated 16 doc files\n- M5 (#228): Renamed nhtsaValue to sourceValue in frontend types/components, updated guide pages\n\n### Key Design Decisions\n- No TRUNCATE migration: Format-aware cache reads (check for success field) let old NHTSA entries expire naturally via 1-year TTL\n- Separate decode router: POST /decode/vin on its own router (not on /extract) since VIN decode accepts JSON, not multipart\n- Error codes: OCR service returns 400/422/503; backend maps 503/422 to 502\n\nFixes #223\nFixes #224\nFixes #225\nFixes #226\nFixes #227\nFixes #228\n\n## Test Plan\n- [x] Backend TypeScript compiles clean (0 errors)\n- [x] Frontend TypeScript compiles clean (0 errors)\n- [x] Backend lint: 0 errors (544 pre-existing warnings)\n- [x] Frontend lint: 0 errors (227 pre-existing warnings)\n- [x] OCR Python tests: 31 pass (13 new VIN decode + 18 existing)\n- [x] Zero NHTSA references in codebase (verified via grep)\n- [ ] Container integration test: VIN decode end-to-end\n- [ ] Existing OCR image-based VIN extraction unaffected

## Summary\n\nReplaces the NHTSA vPIC API integration for VIN string decoding with Google Gemini, routed through the Python OCR microservice (mvp-ocr).\n\n### Changes\n- **M1** (#224): New `POST /decode/vin` endpoint on OCR service using `GeminiEngine.decode_vin()`\n- **M2** (#225): `VinDecodeResponse` type and `OcrClient.decodeVin()` method (JSON POST)\n- **M3** (#226): Rewired `VehiclesController` to use `OcrClient` instead of `NHTSAClient`, moved cache logic to `VehiclesService` with format-aware reads, renamed `nhtsaValue` to `sourceValue`\n- **M4** (#227): Deleted `vehicles/external/nhtsa/` (3 files), removed `VPICVariable`/`VPICResponse`, updated 16 doc files\n- **M5** (#228): Renamed `nhtsaValue` to `sourceValue` in frontend types/components, updated guide pages\n\n### Key Design Decisions\n- **No TRUNCATE migration**: Format-aware cache reads (check for `success` field) let old NHTSA entries expire naturally via 1-year TTL\n- **Separate decode router**: `POST /decode/vin` on its own router (not on `/extract`) since VIN decode accepts JSON, not multipart\n- **Error codes**: OCR service returns 400/422/503; backend maps 503/422 to 502\n\nFixes #223\nFixes #224\nFixes #225\nFixes #226\nFixes #227\nFixes #228\n\n## Test Plan\n- [x] Backend TypeScript compiles clean (0 errors)\n- [x] Frontend TypeScript compiles clean (0 errors)\n- [x] Backend lint: 0 errors (544 pre-existing warnings)\n- [x] Frontend lint: 0 errors (227 pre-existing warnings)\n- [x] OCR Python tests: 31 pass (13 new VIN decode + 18 existing)\n- [x] Zero NHTSA references in codebase (verified via grep)\n- [ ] Container integration test: VIN decode end-to-end\n- [ ] Existing OCR image-based VIN extraction unaffected

egullickson added 5 commits 2026-02-19 03:53:19 +00:00

feat: add VIN decode endpoint to OCR Python service (refs #224) ... a75f7b5583

Add POST /decode/vin endpoint using Gemini 2.5 Flash for VIN string
decoding. Returns structured vehicle data (year, make, model, trim,
body/drive/fuel type, engine, transmission) with confidence score.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

feat: add backend OCR client method for VIN decode (refs #225) ... 3cd61256ba

Add VinDecodeResponse type and OcrClient.decodeVin() method that sends
JSON POST to the new /decode/vin OCR endpoint. Unlike other OCR methods,
this uses JSON body instead of multipart since there is no file upload.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

feat: rewire vehicles controller to OCR VIN decode (refs #226) ... 5cbf9c764d

Replace NHTSAClient with OcrClient in vehicles controller. Move cache
logic into VehiclesService with format-aware reads (Gemini vs legacy
NHTSA entries). Rename nhtsaValue to sourceValue in MatchedField.
Remove vpic config from Zod schema and YAML config files.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

chore: remove NHTSA code and update documentation (refs #227) ... f590421058

Delete vehicles/external/nhtsa/ directory (3 files), remove VPICVariable
and VPICResponse from platform models. Update all documentation to
reflect Gemini VIN decode via OCR service architecture.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

feat: update frontend for Gemini VIN decode (refs #228) ... d96736789e

Rename nhtsaValue to sourceValue in frontend MatchedField type and
VinOcrReviewModal component. Update NHTSA references to vehicle
database across guide pages, hooks, and API documentation.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

egullickson referenced this pull request 2026-02-19 03:53:33 +00:00

feat: Replace NHTSA VIN decode with Google Gemini via OCR service #223

egullickson referenced this issue from a commit 2026-02-20 02:15:03 +00:00

fix: resolve VIN decode cache race, fuzzy matching, and silent failure (refs #229)

egullickson added 1 commit 2026-02-20 02:15:04 +00:00

fix: resolve VIN decode cache race, fuzzy matching, and silent failure (refs #229) ... 361f58d7c6

Prevent lower-confidence Gemini results from overwriting higher-confidence
cache entries, add reverse-contains matching so values like "X5 xDrive35i"
match DB option "X5", and show amber hint when dropdown matching fails.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

egullickson added 1 commit 2026-02-20 02:35:15 +00:00

chore: Change to Gemini 3.0 Flash 5bb44be8bc

egullickson added 1 commit 2026-02-20 02:36:42 +00:00

chore: Gemini 3.0 Flash Preview model bf6742f6ea

egullickson added 1 commit 2026-02-20 02:59:48 +00:00

chore: change google region 781241966c

egullickson merged commit d9df9193dc into main 2026-02-20 03:10:48 +00:00

egullickson deleted branch issue-223-replace-nhtsa-vin-decode-gemini 2026-02-20 03:10:48 +00:00

egullickson referenced this issue from a commit 2026-02-20 03:10:49 +00:00

Merge pull request 'feat: Replace NHTSA VIN decode with Google Gemini via OCR service (#223)' (#229) from issue-223-replace-nhtsa-vin-decode-gemini into main

egullickson referenced this issue from a commit 2026-02-20 03:30:35 +00:00

fix: increase VIN decode timeout to 60s for Gemini cold start (refs #229)

egullickson referenced this pull request 2026-02-20 03:31:45 +00:00

fix: increase VIN decode timeout for Gemini cold start #230

egullickson referenced this issue from a commit 2026-02-20 03:56:31 +00:00

fix: add VIN year code table to Gemini decode prompt (refs #229)

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

status

backlog

status/blocked

status

done

status

in-progress

status

ready

status

review

type

bug

type

chore

type

docs

type

feature

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

egullickson

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: egullickson/motovaultpro#229