Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio GGUF: charge images in the fit and tool-result sizing counts (#14968) (#15014)

Debojyoti Banerjee8b3f6fee6a01
diff --git a/studio/backend/core/inference/context_window.py b/studio/backend/core/inference/context_window.py
index b0111074008..08655ba4ef5 100644
--- a/studio/backend/core/inference/context_window.py
+++ b/studio/backend/core/inference/context_window.py
@@ -39,6 +39,107 @@ def _message_without_unpriced_media(message: dict) -> dict:
return copy
+_IMAGE_PART_TYPES = frozenset(("image_url", "input_image"))
+# One token per repeat on the tokenizers Studio serves, so N repeats count as N tokens (#14968).
+_IMAGE_STAND_IN_TOKEN = " the"
+
+
+def _image_stand_in(tokens: int) -> dict:
+ return {"type": "text", "text": _IMAGE_STAND_IN_TOKEN * max(0, int(tokens))}
+
+
+def _message_with_priced_images(message: dict, price_image: Callable[[dict], int]) -> dict:
+ """Counting copy only: images become stand-ins of their price, audio and video are dropped."""
+ content = message.get("content")
+ if not isinstance(content, list):
+ return message
+ countable = []
+ changed = False
+ for part in content:
+ kind = part.get("type") if isinstance(part, dict) else None
+ if kind in _IMAGE_PART_TYPES:
+ countable.append(_image_stand_in(price_image(part)))
+ changed = True
+ elif kind in _UNPRICED_MEDIA_TYPES:
+ changed = True
+ else:
+ countable.append(part)
+ if not changed:
+ return message
+ copy = dict(message)
+ copy["content"] = countable or ""
+ return copy
+
+
+def messages_with_priced_images(
+ messages: list[dict], price_image: Callable[[dict], int]
+) -> list[dict]:
+ """``messages_without_unpriced_media`` with images charged instead of dropped."""
+ priced = [_message_with_priced_images(message, price_image) for message in messages]
+ return messages if all(before is after for before, after in zip(messages, priced)) else priced
+
+
+def estimate_message_tokens_with_priced_images(
+ message: dict, price_image: Callable[[dict], int]
+) -> int:
+ """Added rather than rendered, so the estimate never serialises a long stand-in."""
+ content = message.get("content")
+ images = (
+ sum(
+ price_image(part)
+ for part in content
+ if isinstance(part, dict) and part.get("type") in _IMAGE_PART_TYPES
+ )
+ if isinstance(content, list)
+ else 0
+ )
+ return estimate_message_tokens_without_unpriced_media(message) + images
+
+
+def image_dimensions(part: dict) -> Optional[tuple[int, int]]:
+ """(width, height) of an inline image part, or None when it cannot be read cheaply."""
+ # Chat Completions nests {"url": ...}; Responses' input_image carries the string directly.
+ image = part.get("image_url")
+ url = image.get("url") if isinstance(image, dict) else image
+ if not isinstance(url, str) or not url.startswith("data:"):
+ return None
+ return _data_url_dimensions(url)
+
+
+_DATA_URL_DIMENSIONS: dict[tuple[int, int], Optional[tuple[int, int]]] = {}
+_DATA_URL_DIMENSIONS_MAX = 256
+
+
+def _data_url_dimensions(url: str) -> Optional[tuple[int, int]]:
+ """Cached because the same image is priced on every count of a tool loop. Keyed on the URL's
+ hash, not the URL: an lru_cache would keep up to 256 multi-MB base64 payloads alive."""
+ key = (hash(url), len(url))
+ try:
+ return _DATA_URL_DIMENSIONS[key]
+ except KeyError:
+ pass
+ dims = _read_data_url_dimensions(url)
+ if len(_DATA_URL_DIMENSIONS) >= _DATA_URL_DIMENSIONS_MAX:
+ _DATA_URL_DIMENSIONS.clear()
+ _DATA_URL_DIMENSIONS[key] = dims
+ return dims
+
+
+def _read_data_url_dimensions(url: str) -> Optional[tuple[int, int]]:
+ try:
+ import base64
+ import io
+
+ from PIL import Image
+
+ _, _, payload = url.partition(",")
+ with Image.open(io.BytesIO(base64.b64decode(payload))) as img:
+ width, height = img.size
+ except Exception:
+ return None
+ return (int(width), int(height)) if width > 0 and height > 0 else None
+
+
def estimate_message_tokens(message: dict) -> int:
try:
return max(1, len(json.dumps(message, ensure_ascii = False)) // 4)
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 5622f116446..afe92bcd4da 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -66,13 +66,14 @@ from core.inference.context_window import (
compact_completed_tool_arguments,
compact_executed_call_arguments,
compact_refused_tool_arguments,
- estimate_message_tokens_without_unpriced_media,
- estimate_messages_tokens_without_unpriced_media,
+ estimate_message_tokens_with_priced_images,
_reply_floor,
estimate_messages_tokens_conservative,
estimate_messages_tokens_dense,
evicted_messages,
fit_rolling_context,
+ image_dimensions,
+ messages_with_priced_images,
messages_without_unpriced_media,
retrieval_budget,
fit_oversized_attachments,
@@ -112,6 +113,7 @@ from core.inference.llama_server_args import (
resolve_ctx_checkpoints,
extra_args_disable_mmproj,
extra_args_image_max_tokens,
+ extra_args_image_min_tokens,
extra_args_mmproj_auto,
extra_args_select_load_mode,
fit_is_enabled_in,
@@ -2717,6 +2719,43 @@ def _mcp_image_tokens(backend) -> int:
return _FALLBACK_IMAGE_TOKENS
+# mtmd's delimiters around an image's embeddings, as admission allows for them.
+_IMAGE_WRAPPER_TOKENS = 128
+# Qwen-VL merges a 2x2 patch square per embedding: 14 px patches on Qwen2/2.5-VL, 16 on Qwen3-VL.
+_MERGED_PATCH_PX = {"qwen2vl_merger": 28, "qwen2.5vl_merger": 28, "qwen3vl_merger": 32}
+# Fixed per image: Gemma 3 pools 896 px to 16 x 16 (258 measured on Gemma 3 4B, ceiling 4224).
+_FIXED_IMAGE_TOKENS = {"gemma3": 256}
+
+
+def _image_token_price(backend, part: dict) -> int:
+ """One image's prompt cost for the fit and tool-result sizing (#14968): the admission ceiling,
+ unless a known projector gives a closer upper bound (the ceiling evicts history that fits)."""
+ ceiling = _mcp_image_tokens(backend)
+ if ceiling <= 0:
+ return 0
+ projector = str(getattr(backend, "_mmproj_projector_type", None) or "").strip().lower()
+ fixed = _FIXED_IMAGE_TOKENS.get(projector)
+ if fixed:
+ return min(ceiling, fixed + _IMAGE_WRAPPER_TOKENS)
+ merged = _MERGED_PATCH_PX.get(projector)
+ dims = image_dimensions(part) if merged else None
+ if dims is None:
+ return ceiling
+ width, height = dims
+ # Ceil, not round: mtmd may round either side up, and this must stay an upper bound.
+ tokens = math.ceil(width / merged) * math.ceil(height / merged)
+ extra_args = getattr(backend, "_extra_args", None)
+ try:
+ cap = extra_args_image_max_tokens(extra_args) or 0
+ # mtmd resizes against --image-min-tokens on its own rounded grid, which this does not model.
+ if extra_args_image_min_tokens(extra_args):
+ return ceiling
+ except Exception: # noqa: BLE001 -- pricing must never break a count
+ cap = 0
+ cap = cap or ceiling - _IMAGE_WRAPPER_TOKENS
+ return min(ceiling, min(tokens, cap) + _IMAGE_WRAPPER_TOKENS)
+
+
# How many times one tool may return a byte-identical result before the model is told the
# call is not going to change. Follows OpenClaw's tool-loop detection, which keys on the
# RESULT rather than the arguments and never intervenes while results are still changing:
@@ -9244,6 +9283,23 @@ class LlamaCppBackend:
def model_identifier(self) -> Optional[str]:
return self._model_identifier
+ def _price_image(self, part: dict) -> int:
+ return _image_token_price(self, part)
+
+ def _countable_messages(self, messages: list[dict]) -> list[dict]:
+ """The counting copy every fit and size probe uses: images charged, audio and video dropped."""
+ from core.inference.mcp_images import prepare_image_turn_boundaries
+
+ # Before pricing: a stand-in hides an image turn from Ministral's alternation fix-up.
+ messages = prepare_image_turn_boundaries(
+ messages,
+ getattr(self, "_chat_template_override", None) or getattr(self, "_chat_template", None),
+ )
+ return messages_with_priced_images(messages, self._price_image)
+
+ def _estimate_countable_message(self, message: dict) -> int:
+ return estimate_message_tokens_with_priced_images(message, self._price_image)
+
@property
def is_vision(self) -> bool:
"""Whether this model takes image input; ``_is_vision`` only records that a
@@ -40824,7 +40880,7 @@ class LlamaCppBackend:
max_tokens = payload["max_tokens"],
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted), None, self.markup_profile
+ self._countable_messages(fitted), None, self.markup_profile
),
None,
None,
@@ -40833,7 +40889,7 @@ class LlamaCppBackend:
continue_final_message = continue_final_message,
should_abort = lambda: bool(cancel_event and cancel_event.is_set()),
),
- estimate_message = estimate_message_tokens_without_unpriced_media,
+ estimate_message = self._estimate_countable_message,
reserve_tokens = _conversation_recall_reserve(thread_id),
sticky_dropped = _sticky,
sticky_is_checkpoint = _sticky_is_checkpoint,
@@ -40866,7 +40922,7 @@ class LlamaCppBackend:
),
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted),
+ self._countable_messages(fitted),
None,
self.markup_profile,
),
@@ -41664,7 +41720,7 @@ class LlamaCppBackend:
),
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted),
+ self._countable_messages(fitted),
_markup_cache,
self.markup_profile,
),
@@ -41674,7 +41730,7 @@ class LlamaCppBackend:
chat_template_kwargs = reasoning_kw,
continue_final_message = continue_flag,
),
- estimate_message = estimate_message_tokens_without_unpriced_media,
+ estimate_message = self._estimate_countable_message,
anchor_ids = (_rolling_anchor_ids | protect) if protect else _rolling_anchor_ids,
)
except Exception:
@@ -41709,7 +41765,7 @@ class LlamaCppBackend:
try:
_tokens = self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(candidate),
+ self._countable_messages(candidate),
_markup_cache,
self.markup_profile,
),
@@ -41880,7 +41936,7 @@ class LlamaCppBackend:
max_tokens = _iteration_max_tokens,
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted),
+ self._countable_messages(fitted),
_markup_cache,
self.markup_profile,
),
@@ -41894,7 +41950,7 @@ class LlamaCppBackend:
),
should_abort = lambda: bool(cancel_event and cancel_event.is_set()),
),
- estimate_message = estimate_message_tokens_without_unpriced_media,
+ estimate_message = self._estimate_countable_message,
anchor_ids = _rolling_anchor_ids,
keeps_boundary = _keeps_compaction_boundary(thread_id),
can_reset = _iteration_can_reset,
@@ -41913,7 +41969,7 @@ class LlamaCppBackend:
# messages, priced by the fit with the catalogue and template.
_prompt_token_offset = int(
truncation.get("prompt_tokens_after") or 0
- ) - estimate_messages_tokens_without_unpriced_media(conversation)
+ ) - sum(self._estimate_countable_message(m) for m in conversation)
if truncation:
_recalled = _archive_and_recall(
conversation,
@@ -41943,7 +41999,7 @@ class LlamaCppBackend:
),
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted),
+ self._countable_messages(fitted),
_markup_cache,
self.markup_profile,
),
@@ -42069,7 +42125,7 @@ class LlamaCppBackend:
max_tokens = _iteration_max_tokens,
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted),
+ self._countable_messages(fitted),
_markup_cache,
self.markup_profile,
),
@@ -42083,7 +42139,7 @@ class LlamaCppBackend:
),
should_abort = lambda: bool(cancel_event and cancel_event.is_set()),
),
- estimate_message = estimate_message_tokens_without_unpriced_media,
+ estimate_message = self._estimate_countable_message,
anchor_ids = _rolling_anchor_ids,
keeps_boundary = _keeps_compaction_boundary(thread_id),
can_reset = _can_reset_epoch(
@@ -42207,15 +42263,13 @@ class LlamaCppBackend:
self._effective_context_length, _iteration_max_tokens
)
if (
- estimate_messages_tokens_dense(
- messages_without_unpriced_media(conversation)
- )
+ estimate_messages_tokens_dense(self._countable_messages(conversation))
> 0.7 * _reply_target
):
try:
_prompt_now = self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(conversation),
+ self._countable_messages(conversation),
_markup_cache,
self.markup_profile,
),
@@ -43750,7 +43804,7 @@ class LlamaCppBackend:
# whole gate.
if (
estimate_messages_tokens_conservative(
- messages_without_unpriced_media(conversation)
+ self._countable_messages(conversation)
)
> 0.7 * _room_target
):
@@ -43779,7 +43833,7 @@ class LlamaCppBackend:
try:
_turn_tokens = self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(
+ self._countable_messages(
[*conversation, _probe_message]
),
_markup_cache,
@@ -43838,7 +43892,7 @@ class LlamaCppBackend:
try:
_after_tokens = self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(_as_if_run),
+ self._countable_messages(_as_if_run),
_markup_cache,
self.markup_profile,
),
@@ -44059,9 +44113,7 @@ class LlamaCppBackend:
try:
_exact_prompt_tokens = self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(
- [*conversation, _size_probe]
- ),
+ self._countable_messages([*conversation, _size_probe]),
_markup_cache,
self.markup_profile,
),
@@ -44092,7 +44144,7 @@ class LlamaCppBackend:
else _exact_prompt_tokens
if _exact_prompt_tokens is not None
else estimate_messages_tokens_dense(
- messages_without_unpriced_media(conversation)
+ self._countable_messages(conversation)
)
+ (
_prompt_token_offset
@@ -44229,7 +44281,7 @@ class LlamaCppBackend:
# is handed to the result.
_spent_after = self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(
+ self._countable_messages(
[*conversation, _size_probe]
),
_markup_cache,
@@ -44761,7 +44813,7 @@ class LlamaCppBackend:
max_tokens = _final_max_tokens,
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted), None, self.markup_profile
+ self._countable_messages(fitted), None, self.markup_profile
),
None,
_final_tools,
@@ -44769,7 +44821,7 @@ class LlamaCppBackend:
chat_template_kwargs = _reasoning_kw,
should_abort = lambda: bool(cancel_event and cancel_event.is_set()),
),
- estimate_message = estimate_message_tokens_without_unpriced_media,
+ estimate_message = self._estimate_countable_message,
anchor_ids = _rolling_anchor_ids,
keeps_boundary = _keeps_compaction_boundary(thread_id),
can_reset = _final_can_reset,
@@ -44800,7 +44852,7 @@ class LlamaCppBackend:
),
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted),
+ self._countable_messages(fitted),
None,
self.markup_profile,
),
@@ -44926,7 +44978,7 @@ class LlamaCppBackend:
max_tokens = max_tokens,
count_tokens = lambda fitted: self.count_chat_tokens(
neutralize_control_markup_in_messages(
- messages_without_unpriced_media(fitted), None, self.markup_profile
+ self._countable_messages(fitted), None, self.markup_profile
),
None,
_final_tools,
@@ -44934,7 +44986,7 @@ class LlamaCppBackend:
chat_template_kwargs = _reasoning_kw,
should_abort = lambda: bool(cancel_event and cancel_event.is_set()),
),
- estimate_message = estimate_message_tokens_without_unpriced_media,
+ estimate_message = self._estimate_countable_message,
anchor_ids = _rolling_anchor_ids,
keeps_boundary = _keeps_compaction_boundary(thread_id),
can_reset = _can_reset_epoch(
@@ -45082,7 +45134,7 @@ class LlamaCppBackend:
return True
try:
_tokens = self.count_chat_tokens(
- messages_without_unpriced_media(candidate_messages),
+ self._countable_messages(candidate_messages),
None,
_final_tools,
strict = True,
diff --git a/studio/backend/core/inference/llama_server_args.py b/studio/backend/core/inference/llama_server_args.py
index 918e08bb18d..159ff338ef6 100644
--- a/studio/backend/core/inference/llama_server_args.py
+++ b/studio/backend/core/inference/llama_server_args.py
@@ -1354,12 +1354,11 @@ def extra_args_disable_mmproj(args: Optional[Iterable[str]]) -> bool:
return disabled
-def extra_args_image_max_tokens(
- args: Optional[Iterable[str]], env: Optional[Mapping[str, str]] = None
+def _extra_args_positive_int(
+ args: Optional[Iterable[str]], flag: str, env_name: str, env: Optional[Mapping[str, str]]
) -> Optional[int]:
- """Return the effective positive ``--image-max-tokens`` value."""
found: Optional[int] = None
- raw_env = (os.environ if env is None else env).get("LLAMA_ARG_IMAGE_MAX_TOKENS")
+ raw_env = (os.environ if env is None else env).get(env_name)
if raw_env:
try:
parsed_env = int(str(raw_env).strip())
@@ -1369,9 +1368,9 @@ def extra_args_image_max_tokens(
found = parsed_env
tokens = [str(a) for a in (args or ())]
for index, raw in enumerate(tokens):
- if raw.startswith("--image-max-tokens="):
+ if raw.startswith(flag + "="):
value = raw.partition("=")[2]
- elif raw == "--image-max-tokens" and index + 1 < len(tokens):
+ elif raw == flag and index + 1 < len(tokens):
value = tokens[index + 1]
else:
continue
@@ -1384,6 +1383,20 @@ def extra_args_image_max_tokens(
return found
+def extra_args_image_max_tokens(
+ args: Optional[Iterable[str]], env: Optional[Mapping[str, str]] = None
+) -> Optional[int]:
+ """Return the effective positive ``--image-max-tokens`` value."""
+ return _extra_args_positive_int(args, "--image-max-tokens", "LLAMA_ARG_IMAGE_MAX_TOKENS", env)
+
+
+def extra_args_image_min_tokens(
+ args: Optional[Iterable[str]], env: Optional[Mapping[str, str]] = None
+) -> Optional[int]:
+ """Return the effective positive ``--image-min-tokens`` value."""
+ return _extra_args_positive_int(args, "--image-min-tokens", "LLAMA_ARG_IMAGE_MIN_TOKENS", env)
+
+
def extra_args_mmproj_auto(
args: Optional[Iterable[str]], env: Optional[Mapping[str, str]] = None
) -> bool:
diff --git a/studio/backend/tests/test_image_token_pricing_14968.py b/studio/backend/tests/test_image_token_pricing_14968.py
new file mode 100644
index 00000000000..46fe3bb4056
--- /dev/null
+++ b/studio/backend/tests/test_image_token_pricing_14968.py
@@ -0,0 +1,306 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Images are charged, not dropped, when a local GGUF chat is fitted and its tool results sized (#14968)."""
+
+import base64
+import io
+import os
+import sys
+import types
+
+import pytest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from core.inference import context_window as cw # noqa: E402
+from core.inference import llama_cpp # noqa: E402
+
+PIL = pytest.importorskip("PIL.Image")
+
+
+def _png(width: int, height: int) -> str:
+ buffer = io.BytesIO()
+ PIL.new("RGB", (width, height)).save(buffer, format = "PNG")
+ return "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode()
+
+
+def _image(url: str) -> dict:
+ return {"type": "image_url", "image_url": {"url": url}}
+
+
+def _flat(price: int):
+ return lambda part: price
+
+
+def _backend(
+ projector = "qwen3vl_merger",
+ extra_args = None,
+ vision = True,
+):
+ return types.SimpleNamespace(
+ is_vision = vision,
+ _mmproj_projector_type = projector,
+ _extra_args = extra_args or [],
+ )
+
+
+def test_an_image_becomes_a_stand_in_of_its_price():
+ message = {"role": "user", "content": [{"type": "text", "text": "look"}, _image("x")]}
+
+ (priced,) = cw.messages_with_priced_images([message], _flat(7))
+
+ assert priced["content"][0] == {"type": "text", "text": "look"}
+ assert priced["content"][1] == {"type": "text", "text": " the" * 7}
+ # The request keeps the real image.
+ assert message["content"][1]["type"] == "image_url"
+
+
+def test_audio_and_video_stay_unpriced():
+ message = {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "hi"},
+ {"type": "input_audio", "input_audio": {"data": "AAAA"}},
+ {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,AAAA"}},
+ ],
+ }
+
+ (priced,) = cw.messages_with_priced_images([message], _flat(7))
+
+ assert priced["content"] == [{"type": "text", "text": "hi"}]
+
+
+def test_a_chat_without_media_is_returned_as_is():
+ messages = [{"role": "user", "content": "hi"}, {"role": "assistant", "content": "yo"}]
+
+ assert cw.messages_with_priced_images(messages, _flat(7)) is messages
+
+
+def test_the_estimate_adds_each_image_price():
+ message = {
+ "role": "user",
+ "content": [{"type": "text", "text": "look"}, _image("x"), _image("y")],
+ }
+
+ text_only = cw.estimate_message_tokens_without_unpriced_media(message)
+
+ assert cw.estimate_message_tokens_with_priced_images(message, _flat(500)) == text_only + 1000
+
+
+def test_image_dimensions_reads_an_inline_png():
+ assert cw.image_dimensions(_image(_png(64, 48))) == (64, 48)
+ assert cw.image_dimensions({"type": "input_image", "image_url": _png(10, 20)}) == (10, 20)
+
+
+def test_image_dimensions_gives_up_on_what_it_cannot_read_cheaply():
+ assert cw.image_dimensions(_image("https://example.com/a.png")) is None
+ assert cw.image_dimensions(_image("data:image/png;base64,bm90IGFuIGltYWdl")) is None
+
+
+def test_a_qwen3_vl_screenshot_is_priced_from_its_size():
+ price = llama_cpp._image_token_price(_backend(), _image(_png(1920, 1080)))
+
+ assert price == 60 * 34 + llama_cpp._IMAGE_WRAPPER_TOKENS
+
+
+def test_image_max_tokens_caps_the_price():
+ backend = _backend(extra_args = ["--image-max-tokens", "1024"])
+
+ price = llama_cpp._image_token_price(backend, _image(_png(1920, 1080)))
+
+ assert price == 1024 + llama_cpp._IMAGE_WRAPPER_TOKENS
+
+
+def test_the_price_never_exceeds_the_admission_ceiling():
+ backend = _backend()
+ ceiling = llama_cpp._mcp_image_tokens(backend)
+
+ assert llama_cpp._image_token_price(backend, _image(_png(8000, 8000))) == ceiling
+
+
+def test_an_unreadable_image_or_unknown_projector_is_charged_the_ceiling():
+ unknown = _backend(projector = "some_future_projector")
+
+ assert llama_cpp._image_token_price(_backend(), _image("https://x/y.png")) == (
+ llama_cpp._mcp_image_tokens(_backend())
+ )
+ assert llama_cpp._image_token_price(unknown, _image(_png(64, 64))) == (
+ llama_cpp._mcp_image_tokens(unknown)
+ )
+
+
+def test_a_gemma3_image_is_priced_at_its_fixed_cost_whatever_its_size():
+ # llama-server charged 258 for every size on Gemma 3 4B; the 4224 ceiling would be 16x that.
+ backend = _backend(projector = "gemma3")
+
+ for size in ((1920, 1080), (64, 64)):
+ price = llama_cpp._image_token_price(backend, _image(_png(*size)))
+ assert price == 256 + llama_cpp._IMAGE_WRAPPER_TOKENS
+ assert llama_cpp._image_token_price(backend, _image("https://x/y.png")) == (
+ 256 + llama_cpp._IMAGE_WRAPPER_TOKENS
+ )
+
+
+def test_the_dimension_cache_does_not_keep_the_image_payload_alive():
+ url = _png(32, 16)
+
+ assert cw.image_dimensions(_image(url)) == (32, 16)
+ assert all(not isinstance(key, str) for key in cw._DATA_URL_DIMENSIONS)
+ assert url not in cw._DATA_URL_DIMENSIONS
+
+
+def test_a_text_only_model_is_charged_nothing():
+ assert llama_cpp._image_token_price(_backend(vision = False), _image(_png(64, 64))) == 0
+
+
+def _screenshot_chat(rounds: int) -> list[dict]:
+ """The report's shape: one message with ten screenshots, then a long tool loop."""
+ screenshot = _png(1920, 1080)
+ messages: list[dict] = [
+ {"role": "system", "content": "You are helpful."},
+ {
+ "role": "user",
+ "content": [{"type": "text", "text": "Read these."}]
+ + [_image(screenshot) for _ in range(10)],
+ },
+ ]
+ for index in range(rounds):
+ call_id = f"call_{index}"
+ messages.append(
+ {
+ "role": "assistant",
+ "content": "",
+ "tool_calls": [
+ {
+ "id": call_id,
+ "type": "function",
+ "function": {"name": "read_file", "arguments": f'{{"path": "f{index}"}}'},
+ }
+ ],
+ }
+ )
+ messages.append({"role": "tool", "tool_call_id": call_id, "content": "line " * 4000})
+ return messages
+
+
+def _fit(messages, backend, priced: bool):
+ estimate = (
+ backend._estimate_countable_message
+ if priced
+ else cw.estimate_message_tokens_without_unpriced_media
+ )
+ countable = backend._countable_messages if priced else cw.messages_without_unpriced_media
+
+ def count(fitted):
+ return sum(estimate(message) for message in countable(fitted))
+
+ return cw.fit_rolling_context(
+ messages,
+ context_length = 65536,
+ max_tokens = 32768,
+ count_tokens = count,
+ estimate_message = estimate,
+ )
+
+
+def test_screenshots_that_outgrow_the_reply_reserve_now_trigger_compaction():
+ backend = _backend()
+ backend._price_image = lambda part: llama_cpp._image_token_price(backend, part)
+ backend._countable_messages = lambda messages: cw.messages_with_priced_images(
+ messages, backend._price_image
+ )
+ backend._estimate_countable_message = (
+ lambda message: cw.estimate_message_tokens_with_priced_images(message, backend._price_image)
+ )
+ messages = _screenshot_chat(rounds = 9)
+
+ _, unpriced = _fit(messages, backend, priced = False)
+ fitted, priced = _fit(messages, backend, priced = True)
+
+ # Text alone (~46k) is under the 49k prompt budget, so the old count kept everything.
+ assert unpriced is None
+ # With the images (~21.7k) charged, older tool rounds go and the screenshots stay.
+ assert priced and priced["dropped_messages"] > 0
+ assert any(
+ isinstance(m.get("content"), list) and m["content"][-1].get("type") == "image_url"
+ for m in fitted
+ )
+
+
+def test_the_backend_counts_images_through_its_own_helpers(monkeypatch):
+ monkeypatch.setattr(llama_cpp.LlamaCppBackend, "is_vision", property(lambda self: True))
+ backend = llama_cpp.LlamaCppBackend.__new__(llama_cpp.LlamaCppBackend)
+ backend._mmproj_projector_type = "qwen3vl_merger"
+ backend._extra_args = []
+ message = {"role": "user", "content": [_image(_png(1920, 1080))]}
+
+ (priced,) = backend._countable_messages([message])
+
+ assert priced["content"][0]["text"] == " the" * (60 * 34 + llama_cpp._IMAGE_WRAPPER_TOKENS)
+ assert backend._estimate_countable_message(message) >= 60 * 34
+
+
+def test_image_min_tokens_charges_the_ceiling():
+ # mtmd upscales a 256 px image to at least 1024 embeddings under --image-min-tokens 1024.
+ backend = _backend(extra_args = ["--image-min-tokens", "1024"])
+
+ price = llama_cpp._image_token_price(backend, _image(_png(256, 256)))
+
+ assert price == llama_cpp._mcp_image_tokens(backend)
+
+
+def test_a_tall_screenshot_is_never_priced_below_its_patch_grid():
+ # 720 px is 22.5 merged patches; mtmd can round it up to 23, so the price must too.
+ price = llama_cpp._image_token_price(_backend(), _image(_png(720, 3200)))
+
+ assert price == 23 * 100 + llama_cpp._IMAGE_WRAPPER_TOKENS
+
+
+def test_a_ministral_image_turn_is_still_balanced_in_the_counting_copy(monkeypatch):
+ from core.inference import mcp_images
+
+ monkeypatch.setattr(llama_cpp.LlamaCppBackend, "is_vision", property(lambda self: True))
+ backend = llama_cpp.LlamaCppBackend.__new__(llama_cpp.LlamaCppBackend)
+ backend._mmproj_projector_type = "pixtral"
+ backend._extra_args = []
+ backend._chat_template = (
+ "{{ raise_exception('After the optional system message, conversation roles must "
+ "alternate user and assistant roles except for tool calls and results.') }}"
+ )
+ turn = mcp_images.placeholder_turn(1)
+ turn["content"] = [
+ part if part.get("type") == "text" else _image(_png(64, 64)) for part in turn["content"]
+ ]
+ assert mcp_images.is_synthetic_image_turn(turn)
+ conversation = [
+ {"role": "user", "content": "Take a screenshot."},
+ {
+ "role": "assistant",
+ "content": "",
+ "tool_calls": [
+ {"id": "c0", "type": "function", "function": {"name": "shot", "arguments": "{}"}}
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c0", "content": "done"},
+ turn,
+ ]
+
+ countable = backend._countable_messages(conversation)
+
+ assert [m["role"] for m in countable] == ["user", "assistant", "tool", "assistant", "user"]
+ # count_chat_tokens repeats the fix-up; it must find nothing left to insert.
+ template = backend._chat_template
+ assert mcp_images.prepare_image_turn_boundaries(countable, template) is countable
+
+
+def test_the_prompt_offset_prices_images_like_the_fit_it_is_taken_from():
+ import inspect
+
+ src = inspect.getsource(llama_cpp.LlamaCppBackend.generate_chat_completion_with_tools)
+ offset = src.split("_prompt_token_offset = int(", 1)[1].split("if truncation:", 1)[0]
+
+ # The fit's count charges images, so the estimate subtracted from it must too, or the
+ # fallback that adds the offset back charges every retained image twice.
+ assert "_estimate_countable_message" in offset
+ assert "without_unpriced_media" not in offset
diff --git a/studio/backend/tests/test_llama_cpp_tool_loop.py b/studio/backend/tests/test_llama_cpp_tool_loop.py
index b035bebd010..8c989b803be 100644
--- a/studio/backend/tests/test_llama_cpp_tool_loop.py
+++ b/studio/backend/tests/test_llama_cpp_tool_loop.py
@@ -6646,6 +6646,9 @@ def test_repeated_note_on_an_mcp_image_keeps_the_base64_out_of_the_tool_text(mon
]
payloads: list[dict] = []
backend = _vision_backend(monkeypatch, streams, payloads, vision = True)
+ # Images are charged in the fit (#14968): with no projector each one costs the ~4.2k
+ # admission ceiling, more than this 4096 window, so price the 6 px screenshot by size.
+ backend._mmproj_projector_type = "qwen3vl_merger"
monkeypatch.setattr(
"core.inference.tools.execute_tool", lambda name, arguments, **_kwargs: fitted
)