From 7d90f4b25a786c9bba5638c2a43a0f51582c536e Mon Sep 17 00:00:00 2001
From: Eric Gullickson <16152721+ericgullickson@users.noreply.github.com>
Date: Thu, 19 Feb 2026 21:55:21 -0600
Subject: [PATCH] fix: add VIN year code table to Gemini decode prompt (refs
 #229)

gemini-3-flash-preview was hallucinating year (e.g., returning 1993
instead of 2023 for position-10 code P). Prompt now includes the full
1980-2039 year code table and position-7 disambiguation rule.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 ocr/app/engines/gemini_engine.py | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/ocr/app/engines/gemini_engine.py b/ocr/app/engines/gemini_engine.py
index 6fa347a..f852cd0 100644
--- a/ocr/app/engines/gemini_engine.py
+++ b/ocr/app/engines/gemini_engine.py
@@ -38,11 +38,26 @@ Return the results as a JSON object with a single "maintenanceSchedule" array.\
 """
 
 _VIN_DECODE_PROMPT = """\
-Given the VIN (Vehicle Identification Number) below, decode it and return the vehicle specifications.
+Decode the following VIN (Vehicle Identification Number) using standard VIN structure rules.
 
 VIN: {vin}
 
-Return the vehicle's year, make, model, trim level, body type, drive type, fuel type, engine description, and transmission type. If a field cannot be determined from the VIN, return null for that field. Return a confidence score (0.0-1.0) indicating overall decode reliability.\
+VIN position reference:
+- Positions 1-3 (WMI): World Manufacturer Identifier (country + manufacturer)
+- Positions 4-8 (VDS): Vehicle attributes (model, body, engine, etc.)
+- Position 9: Check digit
+- Position 10: Model year code. Codes repeat on a 30-year cycle:
+  A=1980/2010 B=1981/2011 C=1982/2012 D=1983/2013 E=1984/2014
+  F=1985/2015 G=1986/2016 H=1987/2017 J=1988/2018 K=1989/2019
+  L=1990/2020 M=1991/2021 N=1992/2022 P=1993/2023 R=1994/2024
+  S=1995/2025 T=1996/2026 V=1997/2027 W=1998/2028 X=1999/2029
+  Y=2000/2030 1=2001/2031 2=2002/2032 3=2003/2033 4=2004/2034
+  5=2005/2035 6=2006/2036 7=2007/2037 8=2008/2038 9=2009/2039
+  To disambiguate: if position 7 is numeric, use the 2010+ year; if alphabetic, use the 1980-2009 year.
+- Position 11: Assembly plant
+- Positions 12-17: Sequential production number
+
+Return the vehicle's year, make, model, trim level, body type, drive type, fuel type, engine description, and transmission type. The year MUST be derived from position 10 using the table above. If a field cannot be determined from the VIN, return null for that field. Return a confidence score (0.0-1.0) indicating overall decode reliability.\
 """
 
 _VIN_DECODE_SCHEMA: dict[str, Any] = {