egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
feat: update frontend for Gemini VIN decode (refs #228)
All checks were successful
Deploy to Staging / Build Images (pull_request) Successful in 6m31s
Details
Deploy to Staging / Deploy to Staging (pull_request) Successful in 23s
Details
Deploy to Staging / Verify Staging (pull_request) Successful in 9s
Details
Deploy to Staging / Notify Staging Ready (pull_request) Successful in 8s
Details
Deploy to Staging / Notify Staging Failure (pull_request) Has been skipped
Details
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 <noreply@anthropic.com>
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)
All checks were successful
Deploy to Staging / Build Images (pull_request) Successful in 6m31s
Details
Deploy to Staging / Deploy to Staging (pull_request) Successful in 52s
Details
Deploy to Staging / Verify Staging (pull_request) Successful in 9s
Details
Deploy to Staging / Notify Staging Ready (pull_request) Successful in 8s
Details
Deploy to Staging / Notify Staging Failure (pull_request) Has been skipped
Details
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 <noreply@anthropic.com>
egullickson added 1 commit 2026-02-20 02:35:15 +00:00
chore: Change to Gemini 3.0 Flash
All checks were successful
Deploy to Staging / Build Images (pull_request) Successful in 36s
Details
Deploy to Staging / Deploy to Staging (pull_request) Successful in 21s
Details
Deploy to Staging / Verify Staging (pull_request) Successful in 8s
Details
Deploy to Staging / Notify Staging Ready (pull_request) Successful in 7s
Details
Deploy to Staging / Notify Staging Failure (pull_request) Has been skipped
Details
5bb44be8bc
egullickson added 1 commit 2026-02-20 02:36:42 +00:00
chore: Gemini 3.0 Flash Preview model
All checks were successful
Deploy to Staging / Build Images (pull_request) Successful in 33s
Details
Deploy to Staging / Deploy to Staging (pull_request) Successful in 51s
Details
Deploy to Staging / Verify Staging (pull_request) Successful in 8s
Details
Deploy to Staging / Notify Staging Ready (pull_request) Successful in 8s
Details
Deploy to Staging / Notify Staging Failure (pull_request) Has been skipped
Details
bf6742f6ea
egullickson added 1 commit 2026-02-20 02:59:48 +00:00
chore: change google region
All checks were successful
Deploy to Staging / Build Images (pull_request) Successful in 38s
Details
Deploy to Staging / Deploy to Staging (pull_request) Successful in 51s
Details
Deploy to Staging / Verify Staging (pull_request) Successful in 9s
Details
Deploy to Staging / Notify Staging Ready (pull_request) Successful in 8s
Details
Deploy to Staging / Notify Staging Failure (pull_request) Has been skipped
Details
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
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 Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
egullickson
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: egullickson/motovaultpro#229
Delete Branch "issue-223-replace-nhtsa-vin-decode-gemini"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?