Skip to main content

Module image_compression

lean_ctx::proxy

Module image_compression 

Source
Expand description

Image compression for vision-model content (#1149).

When LLM requests contain base64-encoded images (Anthropic image blocks, OpenAI image_url with data URIs), this module can reduce their token cost by adjusting resolution and quality — the visual equivalent of text compression.

§Strategy

  1. Detect base64 image content in message arrays.
  2. Classify the image purpose (screenshot, diagram, photo, code screenshot).
  3. Route to optimal resize/quality parameters per class:
    • Screenshots/diagrams: aggressive resize (high text-signal, low spatial detail)
    • Photos: moderate resize (preserve spatial features)
    • Code screenshots: OCR-aware resize (keep text readable)
  4. Re-encode with lower quality JPEG or WebP (for photos) or optimized PNG (for screenshots/diagrams).

§Token economics

Vision tokens are calculated from resolution:

  • Anthropic: (width × height) / 750 tokens per image
  • OpenAI: 170 + (tiles × 85) where tiles = ceil(w/512) × ceil(h/512)

A 1920×1080 screenshot costs ~2765 tokens (Anthropic) or ~850 tokens (OpenAI). Resizing to 1024×576 costs ~786 or ~510 — a 50-72% reduction.

§Configuration

[proxy]
image_compression = true          # default: false (opt-in)
image_max_dimension = 1536        # max width or height
image_quality = 75                # JPEG/WebP quality (1-100)
image_min_size_bytes = 50000      # skip images smaller than this

§Safety

  • Never applied when detail: "high" is explicitly set by the client.
  • Never applied to images with detail: "low" (already minimal tokens).
  • Original preserved in CCR for retrieval if the model needs more detail.

Structs§

ImageCompressResult
Result of attempting to compress an image.
ImageCompressionConfig
Configuration for image compression.
ImageStats
Statistics for monitoring.

Enums§

ImageClass
Image classification for routing to optimal parameters.

Functions§

compress_anthropic_images
Attempt to compress images in an Anthropic request body. Mutates content blocks in-place. Returns number of images compressed.
compress_openai_images
Attempt to compress images in an OpenAI request body. Handles image_url content parts with data URIs.
stats
Snapshot compression statistics.