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`.