fix(query): avoid truncating spaced image filenames - #460

Description

VLM-enhanced retrieval queries can send the wrong local image when a filename contains an image suffix followed by a space. With both chart.png and chart.png v2.png present, a retrieved Image Path: .../chart.png v2.png currently sends the bytes of chart.png.

Match the last image suffix within the same path field, stopping at real or JSON-escaped field separators. The existing image-content, symlink and safe-directory checks still apply to the complete selected path. An unavailable complete path does not fall back to its existing shorter prefix.

Related Issues

Resolves the known limitation recorded by the strict xfail in tests/test_vlm_image_path_lightrag_prompt.py. This follows up on #445, preserving its delimiter handling and use of LightRAG's real prompt builders. No new issue was created.

Changes Made

• Preserve spaced filenames through both query entry points and both naive/mix retrieval modes.
• Turn the existing xfail into passing regression cases that assert the exact image bytes delivered to the vision callback.
• Cover missing, invalid and symlinked complete paths, invalid trailing filename suffixes, adjacent image fields in plain and JSON-escaped contexts, and long escaped-backslash input.

Validation

• Before the fix: all four image-identity regression cases fail by sending the shorter file's bytes.
• Focused query tests: 142 passed on macOS arm64 / Python 3.12.14 / LightRAG 1.4.16.
• Final full suite: 1147 passed, 2 skipped (python -B -m pytest tests/ -q -rs -p no:cacheprovider, with a disposable test directory).
• All five default repository pre-commit hooks passed across all files. git diff --check passed over the complete PR range.
• The final code was reviewed by a separate Codex agent; its filename-fallback finding was fixed and rechecked.

The first full-suite run had six example import failures because the isolated environment lacked the OpenAI client. After preparing that dependency, the two affected example modules passed all 40 tests, and the full-suite result above passed without changing their tests or the source fix.

Tests use local images and LightRAG's real context builders, with retrieval/vision callbacks simulated. No hosted model or paid service was used. The two skipped modules are test_enhanced_markdown_images.py and test_enhanced_markdown_resources.py, which use importorskip for WeasyPrint. The local environment does not include MinerU, PaddleOCR, audio/video model runtimes or WeasyPrint/Pango; CI's full-dependency Python 3.10/3.11/3.12 matrix remains separate.

Checklist

• Changes tested locally
• Independently reviewed
• Unit tests added
• Documentation reviewed; no public API change

Developed with Codex assistance.