feat: gemini-3-flash 5-key pool, hyper-granular prompts, updated Dockerfile for HF Spaces

Dockerfile

@@ -1,23 +1,34 @@
 FROM python:3.11-slim
 
+# ── Labels required by HF Spaces ──────────────────────────────────────────
+LABEL maintainer="Monike123"
+LABEL description="DocVerify AI — HR Document Verification & Extraction"
+
 WORKDIR /app
 
-# System deps for OpenCV, PyMuPDF (libgl1 replaces obsolete libgl1-mesa-glx on Debian Trixie+)
+# ── System dependencies ────────────────────────────────────────────────────
+# libgl1 + libglib2.0-0 → OpenCV
+# poppler-utils          → pdf2image (PDF → PNG rendering)
+# libgomp1               → EasyOCR threading
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 libgomp1 poppler-utils \
+    libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 libgomp1 \
+    poppler-utils \
     && rm -rf /var/lib/apt/lists/*
 
-# Install Python dependencies
+# ── Python dependencies (cached layer — only rebuilds on requirements change) ──
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
 
-# Copy backend code
+# ── Application code ──────────────────────────────────────────────────────
 COPY . .
 
-# Create directories
+# ── Runtime directories ────────────────────────────────────────────────────
 RUN mkdir -p temp_uploads masked_output original_uploads ocr_models
 
-# HF Spaces uses port 7860
+# ── HF Spaces: port MUST be 7860 ──────────────────────────────────────────
 EXPOSE 7860
 
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
+# ── Start server ──────────────────────────────────────────────────────────
+# Workers=1 keeps RAM under 8GB HF free limit (EasyOCR alone is ~1.5GB)
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -1,25 +1,21 @@
 ---
-title: DocVerify API
-emoji: 📄
+title: DocVerify AI - HR Document Verification
+emoji: ??
 colorFrom: green
 colorTo: blue
 sdk: docker
-app_port: 7860
 pinned: false
+license: mit
+app_port: 7860
 ---
 
-# DocVerify API
-
-FastAPI backend for HR document verification: EasyOCR + Gemini 3 Flash + Supabase persistence.
-
-## Secrets (Space Settings)
+# DocVerify AI
 
-| Variable | Description |
-| --- | --- |
-| `DATABASE_URL` | Supabase PostgreSQL connection string |
-| `GEMINI_API_KEYS` | Comma-separated Gemini API keys (failover) |
-| `GEMINI_MODEL` | `gemini-3-flash` |
-| `CORS_ORIGINS` | Netlify frontend URL |
-| `API_KEY` | Optional demo protection |
+AI-powered HR document verification using Gemini 3 Flash vision, EasyOCR, and forensic forgery detection.
 
-See `DEPLOYMENT.md` in the parent repo for full deploy instructions.
+**API runs on port 7860. Set these secrets in Space Settings:**
+- DATABASE_URL
+- GEMINI_API_KEY  
+- GEMINI_API_KEYS (comma-separated failover keys)
+- GEMINI_MODEL=gemini-3-flash
+- CORS_ORIGINS (your Netlify URL)

config.py

@@ -122,6 +122,12 @@ FREE_EMAIL_DOMAINS = {"gmail.com", "yahoo.com", "hotmail.com", "outlook.com", "r
 
 # ── Gemini Vision AI ─────────────────────────────────────────────────────
 GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "")
+# Comma-separated failover key pool (primary key always prepended)
 GEMINI_API_KEYS = [k.strip() for k in os.getenv("GEMINI_API_KEYS", "").split(",") if k.strip()]
+# gemini-3-flash: 1000 RPD free, 1M context, agentic vision on images
 GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3-flash")
 GEMINI_ENABLED = bool(GEMINI_API_KEY or GEMINI_API_KEYS)
+# Image sent to Gemini: max dimension (higher = better accuracy, more tokens)
+GEMINI_MAX_IMAGE_DIMENSION = int(os.getenv("GEMINI_MAX_IMAGE_DIMENSION", "1024"))
+# PDF rendering DPI for Gemini image conversion
+GEMINI_PDF_DPI = int(os.getenv("GEMINI_PDF_DPI", "150"))

ml_utils/gemini_analyzer.py

@@ -1,4 +1,13 @@
-"""Gemini Vision AI analyzer — token-efficient JSON-only document verification."""
+"""Gemini Vision AI analyzer — token-efficient JSON-only document verification.
+
+Key design decisions:
+- gemini-3-flash: 1M context, 1000 RPD free, agentic vision at high media_resolution
+- Single API call returns fields + forgery score + ai_confidence
+- PDFs rendered to PNG image before analysis (never raw PDF bytes)
+- max_output_tokens=400: covers full JSON output with room to spare
+- response_mime_type='application/json' forces valid JSON output
+- All keys rotate via call_with_failover (5-key pool = ~5000 req/day free)
+"""
 
 from __future__ import annotations
 
@@ -17,9 +26,6 @@ from ml_utils.gemini_prompts import build_prompt
 
 logger = logging.getLogger("docverify.gemini")
 
-GEMINI_MAX_IMAGE_DIM = 768
-GEMINI_JPEG_QUALITY = 82
-
 
 @dataclass
 class GeminiResult:
@@ -36,44 +42,54 @@ class GeminiResult:
     key_index: Optional[int] = None
 
 
-def _prepare_image(image_bgr: np.ndarray) -> np.ndarray:
-    from config import GEMINI_MAX_IMAGE_DIMENSION
-
+def _prepare_image(image_bgr: np.ndarray, max_dim: int = 1024) -> np.ndarray:
+    """Resize image preserving aspect ratio. gemini-3-flash handles up to 3072px
+    but 1024px is optimal for token efficiency at high_res mode."""
     h, w = image_bgr.shape[:2]
-    max_dim = min(GEMINI_MAX_IMAGE_DIM, GEMINI_MAX_IMAGE_DIMENSION)
     if max(h, w) > max_dim:
         scale = max_dim / max(h, w)
-        image_bgr = cv2.resize(image_bgr, (int(w * scale), int(h * scale)), interpolation=cv2.INTER_AREA)
+        image_bgr = cv2.resize(
+            image_bgr, (int(w * scale), int(h * scale)),
+            interpolation=cv2.INTER_LANCZOS4
+        )
     return image_bgr
 
 
 def _parse_gemini_response(text: str) -> dict:
+    """Extract JSON from Gemini response, stripping any accidental markdown."""
     text = text.strip()
-    text = re.sub(r"^```(?:json)?\s*", "", text)
-    text = re.sub(r"\s*```$", "", text)
+    # Strip markdown code fences if model added them despite instructions
+    text = re.sub(r"^```(?:json)?\s*", "", text, flags=re.MULTILINE)
+    text = re.sub(r"\s*```$", "", text, flags=re.MULTILINE)
+    # Find the outermost JSON object
     m = re.search(r"\{.*\}", text, re.DOTALL)
     if m:
         return json.loads(m.group(0))
-    raise ValueError(f"No JSON in response: {text[:200]}")
+    raise ValueError(f"No JSON found in Gemini response: {text[:300]}")
 
 
 def _call_gemini_api(api_key: str, pil_img, prompt: str, model_name: str) -> str:
+    """Make a single Gemini API call. Raises on error (key pool handles retries)."""
     import google.generativeai as genai
     from google.generativeai.types import HarmCategory, HarmBlockThreshold
 
     genai.configure(api_key=api_key)
     model = genai.GenerativeModel(model_name)
+
+    # Disable all safety filters — HR documents can contain personal info
     safety = {
         HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_NONE,
         HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_NONE,
         HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_NONE,
         HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_NONE,
     }
+
     gen_cfg = genai.GenerationConfig(
-        temperature=0.0,
-        max_output_tokens=256,
-        response_mime_type="application/json",
+        temperature=0.0,          # deterministic — we want consistent extraction
+        max_output_tokens=400,    # ~300 tokens of JSON + buffer; saves quota
+        response_mime_type="application/json",  # forces valid JSON, no prose
     )
+
     response = model.generate_content(
         [prompt, pil_img],
         safety_settings=safety,
@@ -87,71 +103,124 @@ def analyze_with_gemini(
     doc_type: str,
     pdf_text: Optional[str] = None,
 ) -> GeminiResult:
-    from config import GEMINI_ENABLED, GEMINI_MODEL
+    """Analyze a document image with Gemini Vision.
+
+    Args:
+        image_bgr: OpenCV BGR image (already rendered if from PDF)
+        doc_type: one of aadhaar|pan|caste|experience|education|resume|general
+        pdf_text: optional PDF text layer for extra context (truncated to 300 chars)
+
+    Returns GeminiResult with fields, forgery assessment, and confidence.
+    Falls back gracefully if Gemini is unavailable.
+    """
+    from config import GEMINI_ENABLED, GEMINI_MODEL, GEMINI_MAX_IMAGE_DIMENSION
     from ml_utils.gemini_key_pool import get_api_keys
 
     if not GEMINI_ENABLED or not get_api_keys():
-        return GeminiResult(error="Gemini not configured")
+        return GeminiResult(error="Gemini not configured — set GEMINI_API_KEY")
 
     if image_bgr is None or image_bgr.size == 0:
-        return GeminiResult(error="No image provided")
+        return GeminiResult(error="No image provided to Gemini")
 
     try:
         import PIL.Image
 
-        image_bgr = _prepare_image(image_bgr)
-        _, buf = cv2.imencode(".jpg", image_bgr, [cv2.IMWRITE_JPEG_QUALITY, GEMINI_JPEG_QUALITY])
+        # Prepare: resize to max dimension, convert to PIL for Gemini SDK
+        max_dim = GEMINI_MAX_IMAGE_DIMENSION or 1024
+        img_resized = _prepare_image(image_bgr, max_dim=max_dim)
+        _, buf = cv2.imencode(".jpg", img_resized, [cv2.IMWRITE_JPEG_QUALITY, 88])
         pil_img = PIL.Image.open(io.BytesIO(buf.tobytes()))
 
+        # Build the hyper-granular prompt
         prompt = build_prompt(doc_type)
-        if pdf_text and len(pdf_text) > 20:
-            prompt = f"[pdf_hint:{pdf_text[:200].replace(chr(10), ' ')}]\n{prompt}"
 
+        # Prepend PDF text hint if available (uses ~50 tokens, saves analysis errors)
+        if pdf_text and len(pdf_text.strip()) > 20:
+            # Only send first 300 chars — enough context without wasting tokens
+            hint = pdf_text[:300].replace("\n", " ").strip()
+            prompt = f"[PDF_TEXT_HINT: {hint}]\n\n{prompt}"
+
+        # Call with key-pool failover (5 keys = ~5000 free requests/day)
         raw_text, key_index, err = call_with_failover(
             lambda key: _call_gemini_api(key, pil_img, prompt, GEMINI_MODEL)
         )
 
         if err or not raw_text:
-            return GeminiResult(error=str(err or "Gemini call failed"), used_gemini=False)
-
-        parsed = _parse_gemini_response(raw_text)
-        fields = parsed.get("fields", {}) or {}
-        fields = {k: v for k, v in fields.items() if v is not None and str(v) not in ("null", "", "None")}
+            return GeminiResult(
+                error=str(err or "Gemini call failed — all keys exhausted"),
+                used_gemini=False
+            )
 
-        forgery = parsed.get("forgery", {}) or {}
-        forgery_score = float(forgery.get("score", 0))
-        forgery_reason = str(forgery.get("reason", ""))[:120]
+        logger.info("Gemini[key=%s model=%s] raw: %.200s", key_index, GEMINI_MODEL, raw_text)
 
-        ai_conf = parsed.get("ai_confidence", {}) or {}
-        ai_confidence_score = float(ai_conf.get("score", 50))
-        ai_confidence_reason = str(ai_conf.get("reason", ""))[:120]
+        # Parse the JSON response
+        parsed = _parse_gemini_response(raw_text)
 
-        is_suspicious = forgery_score > 35 and doc_type != "resume"
+        # Extract fields — remove nulls, "null" strings, and empty values
+        raw_fields = parsed.get("fields", {}) or {}
+        fields = {
+            k: v for k, v in raw_fields.items()
+            if v is not None and str(v).strip() not in ("null", "", "None", "n/a", "N/A")
+        }
+
+        # Forgery assessment
+        forgery_data = parsed.get("forgery", {}) or {}
+        forgery_score = float(forgery_data.get("score", 0) or 0)
+        forgery_reason = str(forgery_data.get("reason", "") or "")[:150]
+
+        # AI extraction confidence
+        conf_data = parsed.get("ai_confidence", {}) or {}
+        ai_confidence = float(conf_data.get("score", 50) or 50)
+        ai_confidence_reason = str(conf_data.get("reason", "") or "")[:150]
+
+        # Conservative: only flag as suspicious when score exceeds threshold
+        # Resumes never get forgery flags
+        is_suspicious = (forgery_score > 35) and (doc_type != "resume")
+
+        if is_suspicious:
+            logger.info(
+                "Gemini SUSPICIOUS doc_type=%s score=%.1f reason=%s",
+                doc_type, forgery_score, forgery_reason
+            )
+        else:
+            logger.info(
+                "Gemini CLEAN doc_type=%s forgery=%.1f ai_conf=%.1f fields=%s",
+                doc_type, forgery_score, ai_confidence, list(fields.keys())
+            )
 
         return GeminiResult(
             fields=fields,
             forgery_score=round(forgery_score, 1),
             forgery_reason=forgery_reason,
-            ai_confidence=round(ai_confidence_score, 1),
+            ai_confidence=round(ai_confidence, 1),
             ai_confidence_reason=ai_confidence_reason,
             is_suspicious=is_suspicious,
             used_gemini=True,
-            raw_json=raw_text[:4000],
+            raw_json=raw_text[:4000],  # store for DB, truncated to 4KB
             gemini_model=GEMINI_MODEL,
             key_index=key_index,
         )
 
     except Exception as exc:
-        logger.warning("Gemini analysis failed: %s", exc)
+        logger.warning("Gemini analysis failed: %s", exc, exc_info=True)
         return GeminiResult(error=str(exc), used_gemini=False)
 
 
 def merge_fields(gemini_fields: dict, ocr_fields: dict, doc_type: str) -> dict:
-    merged = dict(ocr_fields)
+    """Merge Gemini + OCR fields. Gemini wins on conflicts; OCR fills gaps.
+
+    This is the 70/30 blend: Gemini is primary (visual AI), OCR is backup.
+    """
+    merged = dict(ocr_fields)  # start with OCR as base
+
     for key, value in gemini_fields.items():
-        if value and str(value).strip() and str(value) not in ("null", "None"):
-            merged[key] = value
+        if value is not None and str(value).strip() not in ("null", "None", ""):
+            merged[key] = value  # Gemini overrides OCR for this key
+
+    # Aadhaar number: always use Gemini's privacy-safe display format
     if doc_type == "aadhaar" and "aadhaar_number" in gemini_fields:
         merged["aadhaar_number_display"] = gemini_fields["aadhaar_number"]
-        merged.pop("aadhaar_number", None)
+        merged.pop("aadhaar_number", None)      # never expose raw number
+        merged.pop("aadhaar_number_raw", None)  # belt and suspenders
+
     return merged

ml_utils/gemini_key_pool.py

@@ -16,8 +16,8 @@ _index = 0
 _daily_counts: dict[str, int] = {}
 _daily_date: date | None = None
 
-# Soft warning threshold per key per day (Gemini 3 Flash free ~20 RPD)
-DAILY_WARN_THRESHOLD = 15
+# gemini-3-flash free tier: 1000 RPD per key; warn at 90% usage
+DAILY_WARN_THRESHOLD = 900
 
 _RETRYABLE_MARKERS = (
     "429",
@@ -63,7 +63,11 @@ def _is_retryable(exc: Exception) -> bool:
 
 
 def call_with_failover(fn: Callable[[str], T]) -> tuple[T | None, int | None, Exception | None]:
-    """Try each API key in round-robin order. Returns (result, key_index, last_error)."""
+    """Try each API key in round-robin order. Returns (result, key_index, last_error).
+
+    On quota/rate-limit errors: cycles through ALL remaining keys before failing.
+    On non-retryable errors: fails immediately (wrong API key, invalid request, etc.).
+    """
     keys = get_api_keys()
     if not keys:
         return None, None, ValueError("No Gemini API keys configured")
@@ -71,22 +75,31 @@ def call_with_failover(fn: Callable[[str], T]) -> tuple[T | None, int | None, Ex
     global _index
     with _lock:
         start = _index % len(keys)
-        _index += 1
+        _index = (_index + 1) % len(keys)
 
     last_error: Exception | None = None
+    tried: list[int] = []
+
     for offset in range(len(keys)):
         key_idx = (start + offset) % len(keys)
         key = keys[key_idx]
+        tried.append(key_idx)
         try:
             result = fn(key)
             _bump_usage(key)
+            logger.debug("Gemini call succeeded with key %d/%d", key_idx + 1, len(keys))
             return result, key_idx, None
         except Exception as exc:
             last_error = exc
-            if _is_retryable(exc) and offset < len(keys) - 1:
-                logger.warning("Gemini key %s failed (%s), trying next key", _mask_key(key), exc)
+            if _is_retryable(exc):
+                logger.warning(
+                    "Gemini key %d/%d quota/rate-limit (%s), trying next",
+                    key_idx + 1, len(keys), _mask_key(key)
+                )
                 continue
-            logger.warning("Gemini key %s failed: %s", _mask_key(key), exc)
+            # Non-retryable (bad key, invalid request, etc.) — fail fast
+            logger.warning("Gemini key %d/%d non-retryable error: %s", key_idx + 1, len(keys), exc)
             return None, key_idx, exc
 
+    logger.error("All %d Gemini keys exhausted. Last error: %s", len(keys), last_error)
     return None, None, last_error

ml_utils/gemini_prompts.py

@@ -1,58 +1,176 @@
-"""Per-document-type Gemini prompt schemas — JSON-only, minimal token output."""
+"""Per-document-type Gemini prompts — hyper-granular, zero-prose JSON output.
 
-# Explicit field keys per doc type (Gemini must only return these)
+Design:
+- Each doc type has visual layout, genuine markers, and specific forgery tells
+- Output is STRICT JSON only — no markdown, no prose, no explanations
+- max_output_tokens=400 covers all fields + forgery + confidence scores
+- Field keys are fixed — Gemini must not invent new keys
+- Forgery scoring is calibrated with real-world examples
+"""
+
+# ── Exact field keys per doc type ─────────────────────────────────────────
 FIELD_SCHEMAS: dict[str, list[str]] = {
     "aadhaar": [
-        "name", "date_of_birth", "gender", "aadhaar_number", "address", "pincode", "state",
+        "name", "date_of_birth", "gender",
+        "aadhaar_number",   # output as XXXX XXXX last4 — never full 12
+        "address", "pincode", "state",
+    ],
+    "pan": [
+        "name", "father_name", "date_of_birth",
+        "pan_number",       # format: AAAAA9999A (5 letters, 4 digits, 1 letter)
     ],
-    "pan": ["name", "father_name", "date_of_birth", "pan_number"],
     "caste": [
-        "person_name", "category", "caste_name", "certificate_number",
-        "issuing_authority", "issue_date", "state", "district",
+        "person_name", "category",          # SC / ST / OBC / EWS / General
+        "caste_name", "certificate_number",
+        "issuing_authority", "issue_date",
+        "state", "district",
     ],
     "experience": [
-        "employee_name", "company_name", "designation", "joining_date",
-        "relieving_date", "employment_duration", "hr_email",
+        "employee_name", "company_name", "designation",
+        "joining_date", "relieving_date", "employment_duration",
+        "hr_email",         # company email (used for verification)
     ],
     "education": [
         "institute_name", "student_name", "degree", "branch",
         "roll_number", "passing_year", "percentage_or_grade",
     ],
     "resume": [
-        "candidate_name", "email", "phone", "skills",
+        "candidate_name", "email", "phone",
+        "skills",           # top 5, comma-separated
         "experience_years", "current_company", "highest_qualification",
     ],
     "general": ["document_type", "key_info"],
 }
 
-_DOC_HINTS: dict[str, str] = {
-    "aadhaar": "UIDAI Aadhaar. Genuine: UIDAI logo, 12-digit number, QR. Forgery: paste boundaries, font mismatch on number.",
-    "pan": "Income Tax PAN. Genuine: Ashoka emblem, AAAAA9999A format. Forgery: wrong format, photo/text resolution mismatch.",
-    "caste": "Govt caste certificate. Genuine: seal, authority name. Forgery: missing seal, font inconsistency.",
-    "experience": "Company experience letter. Genuine: letterhead, dates, signature. Forgery: logo paste, date mismatch.",
-    "education": "Degree/certificate. Genuine: university seal, roll no. Forgery: blurry seal, inserted marks.",
-    "resume": "CV/resume. No forgery scoring needed — extract fields only.",
-    "general": "Identify document type and extract visible key fields.",
+# ── Per-doc layout + forgery knowledge base ───────────────────────────────
+_DOC_KNOWLEDGE: dict[str, str] = {
+
+    "aadhaar": (
+        "UIDAI Aadhaar Card issued by Government of India. "
+        "LAYOUT: Blue/white gradient card. Top: UIDAI logo (left) + 'भारत सरकार / Government of India' (center). "
+        "Body: holder photo (left), name, DOB, gender, address (right). Bottom: 12-digit Aadhaar number in groups of 4 (e.g. 1234 5678 9012). QR code bottom-right corner. "
+        "GENUINE MARKERS: UIDAI text is embossed/crisp, font is uniform Noto Sans across all fields, QR matches the data, holographic strip visible in physical photos. "
+        "FORGERY TELLS (be specific): (1) Aadhaar number region has different JPEG compression block boundaries than surrounding card — visible as slight blur or color banding around digits. "
+        "(2) Name or DOB text has slightly different font weight/spacing compared to other text on same card. "
+        "(3) Photo has different image quality/compression than the rest of the card. "
+        "(4) Address text is typed in different font or has inconsistent line spacing. "
+        "(5) Background gradient is interrupted or shows color seam near text fields. "
+        "(6) QR code is missing, partially obscured, or clearly copy-pasted. "
+        "IMPORTANT: Low image quality, watermarks, and lighting reflections are NOT forgery — score 5-15 for these."
+    ),
+
+    "pan": (
+        "PAN Card issued by Income Tax Department, Government of India. "
+        "LAYOUT: Cream/white background, blue header strip. Ashoka Lion Emblem top-left. "
+        "'आयकर विभाग / Income Tax Department' and 'Govt. of India' in header. "
+        "Holder photo right side. Name, Father's Name, DOB in center. PAN number bottom-center (format: AAAAA9999A). "
+        "Signature strip at bottom. "
+        "GENUINE MARKERS: PAN format exactly AAAAA9999A (5 caps, 4 digits, 1 cap), Ashoka emblem clear, holographic strip. "
+        "FORGERY TELLS: (1) PAN number format wrong (e.g. all digits, wrong length). "
+        "(2) Holder photo has different resolution/compression than card background. "
+        "(3) Name/Father name area has cut-paste boundary (visible pixel seam). "
+        "(4) Ashoka emblem is blurry while text around it is sharp. "
+        "(5) Header text font differs from body text font. "
+        "IMPORTANT: Printed PAN cards scanned at low DPI look grainy — that is NOT forgery."
+    ),
+
+    "caste": (
+        "Indian State Government Caste/Community Certificate. "
+        "LAYOUT: Official government letterhead with state emblem top-center. "
+        "Certificate number top-right. Body: applicant name, parent name, caste, sub-caste, category (SC/ST/OBC/EWS/General), village/district. "
+        "Bottom: Tehsildar/SDM/District Collector designation, official rubber stamp, handwritten signature, date. "
+        "GENUINE MARKERS: Government rubber stamp impression (slightly blurry by nature), handwritten signature, official letterhead, unique certificate number. "
+        "FORGERY TELLS: (1) Stamp is too perfect/sharp — real stamps are imperfect impressions. "
+        "(2) Certificate number appears to be typed over different background. "
+        "(3) Official title and date in different fonts. "
+        "(4) Category field (SC/ST/OBC) appears added on top of existing text. "
+        "IMPORTANT: Poor scan quality, skewed paper, and worn stamps on real documents score 0-15."
+    ),
+
+    "experience": (
+        "Company Experience/Relieving Letter on official letterhead. "
+        "LAYOUT: Company logo + name top. Date top-right. 'To Whom It May Concern' or addressee. "
+        "Body: employee name, designation, joining date, relieving date, employment duration, sometimes CTC. "
+        "Footer: HR Manager name, designation, company seal (optional), signature. "
+        "GENUINE MARKERS: Consistent company letterhead throughout, professional language, company email/website footer. "
+        "FORGERY TELLS: (1) Company logo appears at different DPI/compression than letterhead text. "
+        "(2) Employee name or date appears in different font/size from surrounding text. "
+        "(3) Joining/relieving dates are inconsistent (relieving before joining, future dates). "
+        "(4) Signature or seal appears digitally inserted (uniform white box around it). "
+        "(5) Company name in header differs from company name in body text. "
+        "IMPORTANT: Digital PDFs with consistent fonts are likely genuine — score 0-15."
+    ),
+
+    "education": (
+        "University/Board Degree Certificate or Marksheet. "
+        "LAYOUT: University/Board name + seal top-center. Student photo (for degrees) or absent (marksheets). "
+        "Enrollment/Roll number. Programme/Branch. Examination year/passing year. Marks/Grade/Percentage. "
+        "Registrar/Controller signature + official seal bottom. "
+        "GENUINE MARKERS: University seal is complex (hard to replicate cleanly), embossed or raised seal. "
+        "FORGERY TELLS: (1) Percentage/grade appears in different font or color from surrounding marks. "
+        "(2) University seal is blurry while surrounding text is sharp (opposite of genuine — real seals are slightly blurry). "
+        "(3) Roll number or year has different background color (text was inserted). "
+        "(4) Student name appears corrected or overwritten. "
+        "IMPORTANT: Old paper documents scanned in poor quality are not forgeries — score 0-20."
+    ),
+
+    "resume": (
+        "Resume/CV — user-created document, no forgery scoring needed. "
+        "Extract key professional information only. "
+        "IMPORTANT: Score forgery=0 always for resumes."
+    ),
+
+    "general": (
+        "Unknown document type. First identify what kind of document this is, then extract all visible key-value information. "
+        "Check if it appears to be an official government document or a private/company document."
+    ),
 }
 
 
 def build_prompt(doc_type: str) -> str:
+    """Build a hyper-granular, zero-prose prompt for this document type.
+
+    Target token budget for RESPONSE: ~300 tokens max.
+    The model must return ONLY valid JSON with no wrapping or prose.
+    """
     keys = FIELD_SCHEMAS.get(doc_type, FIELD_SCHEMAS["general"])
-    fields_json = ", ".join(f'"{k}":null' for k in keys)
-    hint = _DOC_HINTS.get(doc_type, _DOC_HINTS["general"])
-    forgery_rule = (
-        'forgery:{"score":0-100,"reason":"max12words"}'
-        if doc_type != "resume"
-        else 'forgery:{"score":0,"reason":"n/a"}'
-    )
-    return (
-        f"HR doc verifier. {hint}\n"
-        f"Return ONLY valid JSON, no markdown:\n"
-        f'{{"fields":{{{fields_json}}},'
-        f'{forgery_rule},'
-        f'"ai_confidence":{{"score":0-100,"reason":"max12words"}}}}\n'
-        "Rules: forgery 0-15=genuine,16-35=quality issue,36-60=suspicious,61+=likely fake. "
-        "ai_confidence=extraction certainty. "
-        "aadhaar_number format XXXX XXXX last4 only. "
-        "Missing=null. No extra keys. No prose."
+    knowledge = _DOC_KNOWLEDGE.get(doc_type, _DOC_KNOWLEDGE["general"])
+
+    # Build field template — null by default, Gemini fills in what it sees
+    fields_template = "{" + ", ".join(f'"{k}": null' for k in keys) + "}"
+
+    # Forgery section differs for resume (never forged)
+    if doc_type == "resume":
+        forgery_template = '{"score": 0, "reason": "n/a"}'
+        forgery_rules = ""
+    else:
+        forgery_template = '{"score": 0-100, "reason": "max 15 words, specific evidence only"}'
+        forgery_rules = (
+            "FORGERY SCORE: 0-15=genuine document; 16-35=quality issues only (NOT forgery); "
+            "36-60=suspicious (specific evidence required); 61-100=likely forged (clear evidence only). "
+            "Only flag as forged if you see SPECIFIC visual evidence listed above. "
+            "Low image quality, compression artifacts, and photo angle are NOT forgery. "
+        )
+
+    prompt = (
+        f"You are a forensic HR document analyst. Analyze this image of an Indian {doc_type} document.\n"
+        f"\n"
+        f"DOCUMENT KNOWLEDGE:\n{knowledge}\n"
+        f"\n"
+        f"OUTPUT RULES (CRITICAL):\n"
+        f"1. Return ONLY valid JSON — zero markdown, zero prose, zero explanation\n"
+        f"2. Use EXACTLY these keys, no additions: {list(keys)}\n"
+        f"3. For missing/unclear fields use null\n"
+        f"4. aadhaar_number: output as 'XXXX XXXX <last4>' to protect privacy\n"
+        f"5. pan_number: output full value (needed for format validation)\n"
+        f"6. Dates: preserve exact format shown on document (e.g. '15/03/1990' or '15 Mar 1990')\n"
+        f"\n"
+        f"{forgery_rules}"
+        f"ai_confidence = your certainty that extracted fields are correct (0=nothing readable, 100=all fields clear and certain).\n"
+        f"\n"
+        f"RETURN THIS EXACT JSON STRUCTURE (fill in values):\n"
+        f'{{"fields": {fields_template}, '
+        f'"forgery": {forgery_template}, '
+        f'"ai_confidence": {{"score": 0-100, "reason": "max 10 words"}}}}'
     )
+    return prompt