AGENTS.md

Operational Notes (DeepSeek-OCR-Demo)

Hugging Face token handling

• HF_TOKEN is not present by default in shell env.
• Local HF CLI token exists at ~/.cache/huggingface/token (used as local fallback).
• Repo now includes:
  • .gitignore (ignores .env and local caches)
  • .env.example (HF_TOKEN=... placeholder only)
  • scripts/fetch_space_logs.sh (Spaces log fetch helper)

Spaces-compatible secret pattern

• Preferred: set HF_TOKEN in Space Settings -> Variables and secrets.
• Local dev: cp .env.example .env, set HF_TOKEN, then:
  • set -a; . ./.env; set +a

Space log access

• Run logs:
  • ./scripts/fetch_space_logs.sh ricklon/DeepSeek-OCR-2-Math run
• Build logs:
  • ./scripts/fetch_space_logs.sh ricklon/DeepSeek-OCR-2-Math build

Current findings from logs

• Build logs looked healthy for commit d6afca6 (no build failure seen).
• Run logs show normal startup and large model download/initialization.
• Observed warning:
  • Flash Attention warning about model init on CPU before GPU move.
  • This warning was already expected in this app flow and not by itself a crash.
• Observed GPU task aborted in UI, but abort stack line was not yet captured in the streamed snippet.

Likely runtime risk (not yet conclusively proven)

• @spaces.GPU(duration=90) may be too short for heavy pages now that equation refinement can trigger multiple extra inferences.
• If abort repeats under load, first mitigation to try is increasing GPU duration for process_image/process_pdf.

Region OCR feature status

• Region OCR UI was added with gr.ImageEditor behind a compatibility guard:
  • HAS_IMAGE_EDITOR = hasattr(gr, "ImageEditor")
• Space config is sdk_version: 6.8.0, which should support ImageEditor.