unique_toolkit 2026.28.0.dev2__py3-none-any.whl → 2026.28.0.dev4__py3-none-any.whl

unique_toolkit/agentic/evaluation/hallucination/utils.py

@@ -16,6 +16,8 @@ from unique_toolkit.agentic.evaluation.schemas import (
 )
 from unique_toolkit.content import ContentReference
 from unique_toolkit.content.schemas import ContentChunk
+from unique_toolkit.language_model.builder import MessagesBuilder
+from unique_toolkit.language_model.infos import ModelCapabilities
 from unique_toolkit.language_model.schemas import (
     LanguageModelMessages,
     LanguageModelStreamResponse,
@@ -104,19 +106,28 @@ def _get_msgs(
     """
     Composes the messages for hallucination analysis based on the provided input and configuration.
 
-    This method composes messages with or without context based on the availability of context texts
-    and history message texts in the input.
+    This method composes messages with or without context based on the availability of context texts,
+    history message texts, and (for vision-capable models) context images in the input.
 
     Args:
-        input (EvaluationMetricInput): The input data that includes context texts and history message texts
-                                      for the analysis.
+        input (EvaluationMetricInput): The input data that includes context texts, history message texts,
+                                      and context images for the analysis.
         config (EvaluationMetricConfig): The configuration settings for composing messages.
         logger (Optional[logging.Logger], optional): The logger used for logging debug information.
 
     Returns:
         The composed messages as per the provided input and configuration.
     """
-    has_context = bool(input.context_texts or input.history_messages)
+    # Context images only count as grounding when the model can actually consume
+    # them; otherwise _compose_msgs drops them and the message would be text-only.
+    model_supports_vision = (
+        ModelCapabilities.VISION in config.language_model.capabilities
+    )
+    has_context = bool(
+        input.context_texts
+        or input.history_messages
+        or (input.context_images and model_supports_vision)
+    )
 
     if has_context:
         _LOGGER.debug("Using context / history for hallucination evaluation.")
@@ -165,6 +176,36 @@ def _compose_msgs(
         else None,
         output_text=input.output_text,
     )
+
+    # When images are provided AND the configured model is vision-capable, build
+    # a multimodal user message (rendered user text + one image part per data
+    # URL) so the model can ground the check against the rendered pages. If the
+    # model lacks VISION we drop the images and fall back to the text-only
+    # message: attaching images to a non-vision model would make the LLM call
+    # fail. Without images the message stays the exact text-only form, so
+    # existing callers are unaffected.
+    context_images = input.context_images or []
+    model_supports_vision = (
+        ModelCapabilities.VISION in config.language_model.capabilities
+    )
+    # When has_context is True for an images-only input, the caller already
+    # confirmed the model is vision-capable, so this branch stays unreachable in
+    # that case and only logs for a genuine non-vision misconfiguration.
+    if context_images and not model_supports_vision:
+        _LOGGER.warning(
+            "Hallucination model %s lacks VISION capability; ignoring "
+            "%d context image(s) and grounding on text only.",
+            config.language_model.name,
+            len(context_images),
+        )
+    if context_images and model_supports_vision:
+        return (
+            MessagesBuilder()
+            .append(system_msg)
+            .image_message_append(content=user_msg_content, images=context_images)
+            .build()
+        )
+
     user_msg = LanguageModelUserMessage(content=user_msg_content)
 
     return LanguageModelMessages([system_msg, user_msg])

unique_toolkit/agentic/evaluation/schemas.py

@@ -34,6 +34,16 @@ class EvaluationMetricInput(BaseModel):
     context_texts: Optional[list[str]] = None
     history_messages: Optional[list[ChatMessage]] = None
     output_text: Optional[str] = None
+    context_images: Optional[list[str]] = Field(
+        default=None,
+        description=(
+            "Optional base64 data URLs (e.g. 'data:image/png;base64,...') of "
+            "context the metric should evaluate against visually, in addition "
+            "to context_texts. Used by metrics that support a multimodal "
+            "(vision) check; ignored by metrics that do not. Defaults to None "
+            "so existing text-only callers are unaffected."
+        ),
+    )
 
     def get_joined_context_texts(self, tag_name: str = "reference") -> str:
         """

unique_toolkit/agentic/evaluation/tests/test_hallucination_utils.py

@@ -20,6 +20,10 @@ from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricInput
 from unique_toolkit.chat.schemas import ChatMessage
 from unique_toolkit.content import ContentReference
 from unique_toolkit.content.schemas import ContentChunk
+from unique_toolkit.language_model.infos import (
+    LanguageModelName,
+    ModelCapabilities,
+)
 from unique_toolkit.language_model.schemas import (
     LanguageModelMessageRole,
     LanguageModelMessages,
@@ -1013,3 +1017,162 @@ def test_compose_msgs__generates_non_empty_messages__from_config_prompts(
     # Assert
     assert len(result.root[0].content) > 0
     assert len(result.root[1].content) > 0
+
+
+_IMAGE_DATA_URL = "data:image/png;base64,QQ=="
+
+
+@pytest.mark.ai
+def test_compose_msgs__builds_multimodal_user_message__with_context_images(
+    hallucination_config: HallucinationConfig,
+) -> None:
+    """
+    Purpose: Verify that context_images produce a multimodal user message.
+    Why this matters: Vision faithfulness needs the rendered pages as image parts.
+    Setup summary: Provide context_images, assert the user message carries text +
+    one image part per data URL.
+    """
+    # Arrange
+    input_data: EvaluationMetricInput = EvaluationMetricInput(
+        input_text="Question",
+        output_text="Output",
+        context_images=[_IMAGE_DATA_URL],
+    )
+
+    # Act
+    result: LanguageModelMessages = _compose_msgs(
+        input_data, hallucination_config, has_context=True
+    )
+
+    # Assert
+    assert len(result.root) == 2
+    user_content = result.root[1].content
+    assert isinstance(user_content, list)
+    text_parts = [p for p in user_content if p.get("type") == "text"]
+    image_parts = [p for p in user_content if p.get("type") == "image_url"]
+    assert len(text_parts) == 1
+    assert len(image_parts) == 1
+    assert image_parts[0]["imageUrl"]["url"] == _IMAGE_DATA_URL
+
+
+@pytest.mark.ai
+def test_compose_msgs__stays_text_only__without_context_images(
+    hallucination_config: HallucinationConfig,
+) -> None:
+    """
+    Purpose: Verify that omitting context_images keeps the exact text-only message.
+    Why this matters: Backward compatibility for all existing (non-vision) callers.
+    Setup summary: No context_images -> user message content is a plain string.
+    """
+    # Arrange
+    input_data: EvaluationMetricInput = EvaluationMetricInput(
+        input_text="Question",
+        context_texts=["Context 1"],
+        output_text="Output",
+    )
+
+    # Act
+    result: LanguageModelMessages = _compose_msgs(
+        input_data, hallucination_config, has_context=True
+    )
+
+    # Assert
+    assert isinstance(result.root[1].content, str)
+
+
+@pytest.mark.ai
+def test_compose_msgs__drops_images__when_model_lacks_vision() -> None:
+    """
+    Purpose: Verify images are dropped when the configured model is not vision-capable.
+    Why this matters: Attaching images to a non-vision model makes the LLM call fail;
+    we must degrade gracefully to a text-only message instead.
+    Setup summary: Configure a text-only model (no VISION capability) with
+    context_images, assert the user message content stays a plain string.
+    """
+    # Arrange
+    text_only_config = HallucinationConfig(
+        enabled=True,
+        language_model=LanguageModelName.AZURE_GPT_4_0613,
+    )
+    assert ModelCapabilities.VISION not in (
+        text_only_config.language_model.capabilities
+    )
+    input_data: EvaluationMetricInput = EvaluationMetricInput(
+        input_text="Question",
+        output_text="Output",
+        context_images=[_IMAGE_DATA_URL],
+    )
+
+    # Act
+    result: LanguageModelMessages = _compose_msgs(
+        input_data, text_only_config, has_context=True
+    )
+
+    # Assert
+    assert isinstance(result.root[1].content, str)
+
+
+@pytest.mark.ai
+def test_get_msgs__treats_context_images_as_context(
+    hallucination_config: HallucinationConfig,
+) -> None:
+    """
+    Purpose: Verify that context_images alone count as context in _get_msgs.
+    Why this matters: A vision-only turn must use the grounded (has_context) prompt
+    and build the multimodal message.
+    Setup summary: Provide only context_images; assert the system prompt matches the
+    has_context variant and the user message is multimodal.
+    """
+    # Arrange
+    image_only: EvaluationMetricInput = EvaluationMetricInput(
+        input_text="Question",
+        output_text="Output",
+        context_images=[_IMAGE_DATA_URL],
+    )
+    grounded: EvaluationMetricInput = EvaluationMetricInput(
+        input_text="Question",
+        context_texts=["Context 1"],
+        output_text="Output",
+    )
+
+    # Act
+    result: LanguageModelMessages = _get_msgs(image_only, hallucination_config)
+    grounded_result: LanguageModelMessages = _get_msgs(grounded, hallucination_config)
+
+    # Assert
+    assert result.root[0].content == grounded_result.root[0].content
+    assert isinstance(result.root[1].content, list)
+
+
+@pytest.mark.ai
+def test_get_msgs__ignores_context_images__when_model_lacks_vision() -> None:
+    """
+    Purpose: Verify image-only input is not treated as context for a non-vision model.
+    Why this matters: _compose_msgs drops the images for a non-vision model, so the
+    grounded prompt would otherwise claim references that are never sent. has_context
+    must reflect the message actually delivered.
+    Setup summary: Configure a text-only model with only context_images; assert the
+    system prompt matches the ungrounded variant and the user message is text-only.
+    """
+    # Arrange
+    text_only_config = HallucinationConfig(
+        enabled=True,
+        language_model=LanguageModelName.AZURE_GPT_4_0613,
+    )
+    image_only: EvaluationMetricInput = EvaluationMetricInput(
+        input_text="Question",
+        output_text="Output",
+        context_images=[_IMAGE_DATA_URL],
+    )
+    no_context: EvaluationMetricInput = EvaluationMetricInput(
+        input_text="Question",
+        output_text="Output",
+    )
+
+    # Act
+    result: LanguageModelMessages = _get_msgs(image_only, text_only_config)
+    no_context_result: LanguageModelMessages = _get_msgs(no_context, text_only_config)
+
+    # Assert
+    assert result.root[0].content == no_context_result.root[0].content
+    assert isinstance(result.root[1].content, str)

{unique_toolkit-2026.28.0.dev2.dist-info → unique_toolkit-2026.28.0.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.28.0.dev2
+Version: 2026.28.0.dev4
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>
@@ -16,7 +16,7 @@ Requires-Dist: sseclient>=0.0.27,<0.0.28
 Requires-Dist: openai>=1.105.0,<3
 Requires-Dist: platformdirs>=4.0.0,<5
 Requires-Dist: pillow>=12.1.1
-Requires-Dist: unique-sdk>=2026.28.0.dev3,<2026.28.0rc0
+Requires-Dist: unique-sdk>=2026.28.0.dev5,<2026.28.0rc0
 Requires-Dist: jambo>=0.1.2,<0.2
 Requires-Dist: jinja2>=3.1.6,<4
 Requires-Dist: docxtpl>=0.20.1,<0.21

{unique_toolkit-2026.28.0.dev2.dist-info → unique_toolkit-2026.28.0.dev4.dist-info}/RECORD

@@ -99,14 +99,14 @@ unique_toolkit/agentic/evaluation/hallucination/prompts/__init__.py,sha256=4KFYM
 unique_toolkit/agentic/evaluation/hallucination/prompts/system_prompt.j2,sha256=sDUX6G645Ba40D_qKu4cUI8g-sJOfG8JpZreTNFgf7M,2616
 unique_toolkit/agentic/evaluation/hallucination/prompts/user_prompt.j2,sha256=mD_qE9fOkyc1XXrebFt097ddx8bTlA6lbY04hKSQmWs,273
 unique_toolkit/agentic/evaluation/hallucination/service.py,sha256=WJF1f45uHnYLx1S4TW31bSFobFpV-YlOS3G_zMhuBVU,2512
-unique_toolkit/agentic/evaluation/hallucination/utils.py,sha256=nXbKyQksHVkmJIFWXW53-QaET_WrVYJOiUS4eDvQGaE,12091
+unique_toolkit/agentic/evaluation/hallucination/utils.py,sha256=3j2iQ89pMV9DFZ-7asBiHMZfZqSt0gMalZT_d1GRhuo,14068
 unique_toolkit/agentic/evaluation/output_parser.py,sha256=0FDo8YY_Dc4qlTNeYyQkznzIFj9aX9wMrLOTbhhTl6g,1418
-unique_toolkit/agentic/evaluation/schemas.py,sha256=m9JMCUmeqP8KhsJOVEzsz6dRXUe1uKw-bxRDtn5qwvM,3156
+unique_toolkit/agentic/evaluation/schemas.py,sha256=dadCyJjHbl469Crph2kEWll1kC_jpVkHaaY9wyXAK-E,3640
 unique_toolkit/agentic/evaluation/tests/fixtures.py,sha256=Q-ughTfDiAdsMKbBVGzFiBucFdAx-FXgJ9iqp5xMyPs,2801
 unique_toolkit/agentic/evaluation/tests/test_config.py,sha256=p7xFQ7KE_yU8jGpqYA7ntAYe5Vln33wd6nwv3FM9XfI,8327
 unique_toolkit/agentic/evaluation/tests/test_context_relevancy_service.py,sha256=NcSOyBJ_lqYehtlraZPo9RLutCitTP76kvkuyogSD2A,9477
 unique_toolkit/agentic/evaluation/tests/test_hallucination_constants.py,sha256=A77nRcniI7hUf640f1sTvCAibQbJE30ikbz1RX4fltw,20478
-unique_toolkit/agentic/evaluation/tests/test_hallucination_utils.py,sha256=Mii94lYFh8H_OaJyZSApdh45Sz3CN5r5q9GVsQgOTYA,31856
+unique_toolkit/agentic/evaluation/tests/test_hallucination_utils.py,sha256=ogds7jUwwGJHdabhayhEY_1JbiaVv7Fxh58TMwgbqgw,37537
 unique_toolkit/agentic/evaluation/tests/test_output_parser.py,sha256=KfltytmvqnPWLhmZpBXqcRmnlYorw_USwM5rkLVv8so,5179
 unique_toolkit/agentic/evaluation/tests/test_prompt_loaders.py,sha256=zBREdlKf5tdDyB8XSaNgpQv3-tuZJoYteeJrp6WMWDM,11897
 unique_toolkit/agentic/evaluation/utils.py,sha256=HmyPaDV8wdW-_gOjjW-wDaMKgdrsP5-SHP7OqTmGI_A,264
@@ -402,6 +402,6 @@ unique_toolkit/short_term_memory/service.py,sha256=Qo-c9yxzC1ZEEHJyIG_vnRs_ef0SK
 unique_toolkit/smart_rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 unique_toolkit/smart_rules/compile.py,sha256=vRe0aMJWuVIK-VsqomgxQImzke7MDmwgSxxJfYCa7zw,1386
 unique_toolkit/test_utilities/events.py,sha256=FLrhMh0A_mQutAUjoD0FdMcVQ4Gq31r35OVGzRjvLro,6760
-unique_toolkit-2026.28.0.dev2.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-unique_toolkit-2026.28.0.dev2.dist-info/METADATA,sha256=-L08qC8wJBPOovWUmGDdBRkhEdhxxYe-8LGLw6dW_Rs,7426
-unique_toolkit-2026.28.0.dev2.dist-info/RECORD,,
+unique_toolkit-2026.28.0.dev4.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+unique_toolkit-2026.28.0.dev4.dist-info/METADATA,sha256=zwb866qNcc6wQI3bmlKEsLMjuGurNHVXbuFbAcCeDuE,7426
+unique_toolkit-2026.28.0.dev4.dist-info/RECORD,,