chore(test): commit Makefile and testing scripts

Makefile

@@ -102,3 +102,32 @@ clean-docker: ## Clean up Docker images and containers
 	docker stop kybtech-dots-ocr || true
 	docker rm kybtech-dots-ocr || true
 	docker rmi kybtech-dots-ocr || true
+
+# -----------------------------
+# Debug testing helpers
+# -----------------------------
+.PHONY: debug-test-local debug-test-hf debug-test
+
+debug-test-local: ## Run debug curl test against local server
+	./scripts/test_debug_ocr.sh -u http://localhost:7860 -f scripts/tom_id_card_front.jpg -d
+
+debug-test-hf: ## Run debug curl test against HF Space (set HF_URL var)
+	@if [ -z "$(HF_URL)" ]; then echo "HF_URL not set. Example: make debug-test-hf HF_URL=https://your-space.hf.space"; exit 1; fi
+	./scripts/test_debug_ocr.sh -u $(HF_URL) -f scripts/tom_id_card_front.jpg -d
+
+# debug-test allows overriding URL/FILE/ROI/DEBUG via envs
+# Example:
+#   make debug-test URL=https://space.hf.space FILE=scripts/tom_id_card_front.jpg ROI='{"x1":0,"y1":0,"x2":1,"y2":0.5}' DEBUG=1
+
+debug-test: ## Run debug curl test with overrides: URL, FILE, ROI, DEBUG
+	@URL=${URL:-http://localhost:7860} \
+	FILE=${FILE:-scripts/tom_id_card_front.jpg} \
+	ROI=${ROI:-} \
+	DBG=${DEBUG:-0} \
+	sh -c '\
+	  CMD="./scripts/test_debug_ocr.sh -u $$URL -f $$FILE"; \
+	  if [ "$$DBG" = "1" ]; then CMD="$$CMD -d"; fi; \
+	  if [ -n "$$ROI" ]; then CMD="$$CMD -r '$$ROI'"; fi; \
+	  echo "Running: $$CMD"; \
+	  eval $$CMD \
+	'

scripts/README_TESTING.md

@@ -213,3 +213,21 @@ These metrics can be integrated with monitoring systems like Prometheus or DataD
 ./run_tests.sh -e staging    # Staging environment
 ./run_tests.sh -e production # Production environment
 ```
+
+---
+
+### 5. `test_debug_ocr.sh` - Per-request debug logging via curl
+
+Use this for quick, dependency-light testing of the server-side debug mode that prints OCR snippets, extracted fields, and MRZ details to logs.
+
+**Usage:**
+```bash
+# Local server (per-request debug on)
+./test_debug_ocr.sh -u http://localhost:7860 -f tom_id_card_front.jpg -d
+
+# Hugging Face Space (replace with your Space URL)
+./test_debug_ocr.sh -u https://<your-space>.hf.space -f tom_id_card_front.jpg -d \
+  -r '{"x1":0,"y1":0,"x2":1,"y2":0.5}'
+```
+
+You can also enable debug globally on the server with `DOTS_OCR_DEBUG=1`. The script only toggles the request-level flag via `-d`.

scripts/test_debug_ocr.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Quick tester for Dots.OCR debug mode using curl.
+#
+# Usage examples:
+#   scripts/test_debug_ocr.sh -u http://localhost:7860 -f scripts/tom_id_card_front.jpg -d
+#   scripts/test_debug_ocr.sh -u https://<your-hf-space>.hf.space -f scripts/tom_id_card_front.jpg -d -r '{"x1":0,"y1":0,"x2":1,"y2":0.5}'
+#
+# Notes:
+# - The `debug` form field enables per-request debug logging on the server.
+# - You can also set env DOTS_OCR_DEBUG=1 on the server to enable globally.
+
+set -euo pipefail
+
+API_URL="http://localhost:7860"
+FILE_PATH=""
+ROI_JSON=""
+ENABLE_DEBUG=false
+
+usage() {
+  echo "Usage: $0 -u <api_url> -f <image_or_pdf> [-d] [-r '<roi-json>']" >&2
+  echo "  -u  API base URL (default: ${API_URL})" >&2
+  echo "  -f  Path to image/PDF file to upload" >&2
+  echo "  -d  Enable per-request debug logging (adds -F debug=true)" >&2
+  echo "  -r  ROI JSON string, e.g. '{\"x1\":0,\"y1\":0,\"x2\":1,\"y2\":0.5}'" >&2
+  exit 1
+}
+
+while getopts ":u:f:r:d" opt; do
+  case ${opt} in
+    u) API_URL="$OPTARG" ;;
+    f) FILE_PATH="$OPTARG" ;;
+    r) ROI_JSON="$OPTARG" ;;
+    d) ENABLE_DEBUG=true ;;
+    *) usage ;;
+  esac
+done
+
+if [[ -z "$FILE_PATH" ]]; then
+  echo "Error: file path is required." >&2
+  usage
+fi
+
+if [[ ! -f "$FILE_PATH" ]]; then
+  echo "Error: file not found: $FILE_PATH" >&2
+  exit 2
+fi
+
+echo "🚀 Testing Dots.OCR API at $API_URL"
+echo "File: $FILE_PATH"
+if [[ -n "$ROI_JSON" ]]; then
+  echo "ROI:  $ROI_JSON"
+fi
+echo "Debug: $ENABLE_DEBUG"
+
+CURL_ARGS=(
+  -sS -X POST "$API_URL/v1/id/ocr"
+  -F "file=@$FILE_PATH"
+)
+
+if [[ -n "$ROI_JSON" ]]; then
+  CURL_ARGS+=( -F "roi=$ROI_JSON" )
+fi
+
+if [[ "$ENABLE_DEBUG" == true ]]; then
+  CURL_ARGS+=( -F "debug=true" )
+fi
+
+# Pretty-print with jq if available
+if command -v jq >/dev/null 2>&1; then
+  curl "${CURL_ARGS[@]}" | jq '.'
+else
+  echo "(Install jq for pretty JSON)"
+  curl "${CURL_ARGS[@]}"
+fi
+
+echo ""
+echo "Done. Check server logs for detailed debug output when enabled."
+
+