fix(perception): disable PaddleOCR doc-unwarping for screenshots

PaddleOCR's OCR.yaml pipeline defaults to use_doc_orientation_classify
and use_doc_unwarping enabled, which are meant for photographed paper
documents. Applied to a flat, upright device screenshot, UVDoc
geometrically warps the image before detection, and returns box
coordinates in that warped space with no inverse mapping back to the
original image.

Verified on a real screenshot: with unwarping on, the same detected
element ("新项目") shifts from y=158 to y=71 versus the original image,
and 2 boxes near the top edge (status bar time/battery) are dropped
entirely. Disabling both flags by default (still overridable via
explicit kwargs) makes detected boxes match the original screenshot.

perception/ocr.py

@@ -33,6 +33,16 @@ class OCRBox:
 
 class PaddleOCREngine:
     def __init__(self, **kwargs: Any) -> None:
+        # Device screenshots are already upright, flat digital captures, not
+        # photographed paper documents, so PaddleOCR's document-preprocessing
+        # models (orientation classification + UVDoc unwarping) have nothing
+        # real to correct. Left at their library defaults (True), they still
+        # run, geometrically warp the image, and detect/recognize text against
+        # that warped image, returning box coordinates that no longer line up
+        # with the original screenshot. Callers can still opt back in via an
+        # explicit kwarg.
+        kwargs.setdefault("use_doc_orientation_classify", False)
+        kwargs.setdefault("use_doc_unwarping", False)
         self.kwargs = kwargs
         self._engine: Any | None = None
 

pyproject.toml

@@ -9,7 +9,7 @@ dependencies = [
     "httpx>=0.27.0",
     "mcp>=1.27,<2",
     "openai>=1.0.0",
-    "paddlepaddle>=3.0.0",
+    "paddlepaddle>=3.0.0,<3.3.0",
     "paddleocr>=3.0.0",
 ]
 

tests/test_ocr.py

@@ -4,7 +4,24 @@ import numpy as np
 import pytest
 
 from core.models import Bounds
-from perception.ocr import OCRBox, parse_paddle_result, run_ocr
+from perception.ocr import OCRBox, PaddleOCREngine, parse_paddle_result, run_ocr
+
+
+def test_paddle_ocr_engine_disables_doc_preprocessing_by_default() -> None:
+    # Screenshots are flat, upright digital captures, not photographed paper
+    # documents: PaddleOCR's document-unwarping preprocessing has nothing real
+    # to correct and instead warps the image, so detected box coordinates no
+    # longer line up with the original screenshot.
+    engine = PaddleOCREngine(lang="ch")
+
+    assert engine.kwargs["use_doc_orientation_classify"] is False
+    assert engine.kwargs["use_doc_unwarping"] is False
+
+
+def test_paddle_ocr_engine_lets_callers_override_doc_preprocessing() -> None:
+    engine = PaddleOCREngine(use_doc_unwarping=True)
+
+    assert engine.kwargs["use_doc_unwarping"] is True
 
 
 def test_parse_paddle_result_accepts_ndarray_fields() -> None:

uv.lock

@@ -421,7 +421,7 @@ requires-dist = [
     { name = "mcp", specifier = ">=1.27,<2" },
     { name = "openai", specifier = ">=1.0.0" },
     { name = "paddleocr", specifier = ">=3.0.0" },
-    { name = "paddlepaddle", specifier = ">=3.0.0" },
+    { name = "paddlepaddle", specifier = ">=3.0.0,<3.3.0" },
 ]
 
 [package.metadata.requires-dev]
@@ -1074,7 +1074,7 @@ wheels = [
 
 [[package]]
 name = "paddlepaddle"
-version = "3.3.1"
+version = "3.2.2"
 source = { registry = "https://mirrors.aliyun.com/pypi/simple" }
 dependencies = [
     { name = "httpx" },
@@ -1084,13 +1084,13 @@ dependencies = [
     { name = "pillow" },
     { name = "protobuf" },
     { name = "safetensors" },
-    { name = "setuptools" },
     { name = "typing-extensions" },
 ]
 wheels = [
-    { url = "https://mirrors.aliyun.com/pypi/packages/65/f8/bebb829227ac5574454b4342bcf512dbb02268118b62222fc7c1b420a3ef/paddlepaddle-3.3.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2ce30bfb0023d8c9314b1413ca7a775a4ddd076e4551e74fbed2366cf1395c98" },
-    { url = "https://mirrors.aliyun.com/pypi/packages/56/8d/5a700dc20c0d3d581f1d429f95f5064eb766c2818c5a05992dfef66b0765/paddlepaddle-3.3.1-cp313-cp313-manylinux1_x86_64.whl", hash = "sha256:4f28038427649bb2fcfd4d52efa85ed8311df19122b4ebedc942484a0b57b032" },
-    { url = "https://mirrors.aliyun.com/pypi/packages/f4/c8/408b9e94ac2e10a55c1122b787359f7a6f79ef894ee1d57d78c5cca838d0/paddlepaddle-3.3.1-cp313-cp313-win_amd64.whl", hash = "sha256:1203e2e1114b49e73a8440b68837ce5c93fdab51fe4838c5e5874ab40f58f747" },
+    { url = "https://mirrors.aliyun.com/pypi/packages/ee/14/af48dcf222555f83480c8d50662944c34952b601b1f2b2264f5afe7e073a/paddlepaddle-3.2.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f7e9bc0469d13d99925cd766c4a6ceeb5ab6043b790dd415ce076fbbebb39074" },
+    { url = "https://mirrors.aliyun.com/pypi/packages/ae/95/909e963330997da9da7e3f51337c19a022d8ba2b7863aaca5694aeca26cf/paddlepaddle-3.2.2-cp313-cp313-manylinux1_x86_64.whl", hash = "sha256:c4f485596a686ea72ab0ddffc9e41178f456314a99d4538f5d181a0156a927fa" },
+    { url = "https://mirrors.aliyun.com/pypi/packages/4a/76/74aed8ab5ac6961145bf3e0907a26ffccb69e35cafcd18e4046bb68565dd/paddlepaddle-3.2.2-cp313-cp313-manylinux2014_aarch64.whl", hash = "sha256:b03569ba151ac50aa730955c65dfa571fe7ae71f94574c94e8bfe5e0913a7d9c" },
+    { url = "https://mirrors.aliyun.com/pypi/packages/e5/b8/8a9f7b673c6ac0f26d8eb49cf8e7689e2f3f5cadd2fc6569ee5b9a4da81d/paddlepaddle-3.2.2-cp313-cp313-win_amd64.whl", hash = "sha256:a05d126c234d3985439cedf1f1005b109c3591ec2a0c5b59ca74a94b693eb283" },
 ]
 
 [[package]]