robotframework-aivision 0.2.0a1__py3-none-any.whl

AIVision/__init__.py

@@ -0,0 +1,29 @@
+# MIT License
+#
+# Copyright (c) 2025 Róbert Malovec
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+Main Robot Framework AI Library plugin entrypoint
+"""
+
+from .library import AIVision
+
+__all__ = ["AIVision"]

AIVision/font/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Anton Project Authors (https://github.com/googlefonts/AntonFont.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

AIVision/genai.py

@@ -0,0 +1,337 @@
+# MIT License
+#
+# Copyright (c) 2025 Róbert Malovec
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from .platforms import Platforms
+from openai import OpenAI
+import os
+import base64
+
+
+class AIPlatform:
+    """Configuration class for AI platform settings."""
+    DEFAULT_IMG_DETAIL = "high"
+
+    def __init__(self, platform: Platforms = None, base_url: str = None,
+                 api_key: str = None, model: str = None, image_detail: str = DEFAULT_IMG_DETAIL):
+        """
+        Initialize AI platform configuration.
+
+        Args:
+            platform: Platform enum value
+            base_url: Custom base URL (overrides platform default)
+            api_key: API key for authentication
+            model: Model name (overrides platform default)
+            image_detail: Image detail level for vision models
+        """
+        self.platform = platform
+        self.base_url = base_url or (platform.value["default_base_url"] if platform else None)
+        self.model = model or (platform.value["default_model"] if platform else None)
+        self.detail = image_detail
+        self.api_key = api_key
+        self.supports_vision = platform.value.get("supports_vision", False) if platform else False
+
+        # Validate API key requirement
+        if platform and platform.value.get("api_key_required", False) and not api_key:
+            raise ValueError(f"{platform.name} requires an API key")
+
+
+class GenAI:
+    """
+    GenAI class for interacting with multiple AI platforms using OpenAI-compatible API.
+    Supports Ollama, Perplexity, and is easily extensible for other providers.
+    """
+
+    AUTOMATOR_INSTRUCTION = """
+You are a response system for Robot Framework, specialized in test automation. 
+Your task is to evaluate an input instruction (assertion) against one or more provided images. 
+You must verify whether the assertion holds true based on the visual content of the images.
+Make sure you observe images in every detail - all the logos, texts, titles, buttons, elements, inputs.
+
+Your response must be strictly formatted like this:
+
+RESULT: // PASS if assertion is verified, FAIL if not
+EXPLANATION: 
+<brief explanation if TRUE, detailed explanation if FALSE>
+
+
+When the assertion is TRUE:
+Confirm the assertion and provide a brief explanation of why it was verified successfully.
+
+When the assertion is FALSE:
+Explain in detail what was wrong and why the assertion could not be verified.
+
+Highlight any visual discrepancies, missing elements, or mismatches.
+
+Example Inputs and Outputs:
+
+Input Instruction: "The login button is visible and labeled 'Sign In'"
+Provided Image: [screenshot of a login form]
+
+Response when TRUE:
+
+RESULT: pass
+EXPLANATION: 
+1. The login button is clearly visible
+2. The login button is labeled 'Sign In' as expected.
+
+
+Response when FALSE:
+
+RESULT: fail
+EXPLANATION:
+1. The login button is either not visible or not labeled 'Sign In'.
+2. The visible button is labeled 'Log In' instead.
+
+
+Ensure no other text is provided in the response.
+    """
+
+    def __init__(self, platform: Platforms = Platforms.Ollama, base_url: str = None,
+                 api_key: str = None, model: str = None, image_detail: str = None,
+                 simple_response: bool = True, initialize: bool = True,
+                 system_prompt: str = AUTOMATOR_INSTRUCTION):
+        """
+        Initialize GenAI instance.
+
+        Args:
+            platform: AI platform to use (default: Ollama)
+            base_url: Custom base URL for API endpoint
+            api_key: API key for authentication
+            model: Model name to use
+            image_detail: Detail level for image processing
+            simple_response: Return simplified responses
+            initialize: Initialize client immediately
+            system_prompt: Main AI System prompt specifying Gen AI behavior
+        """
+        self.client = None
+        self.simple_response = simple_response
+        self.system_prompt = system_prompt or self.AUTOMATOR_INSTRUCTION
+
+        # Set default API key for platforms that don't require real keys
+        if platform == Platforms.Ollama and not api_key:
+            api_key = "ollama"  # Required by OpenAI client but ignored by Ollama
+
+        self.ai_platform = AIPlatform(
+            platform=platform,
+            base_url=base_url,
+            api_key=api_key,
+            model=model,
+            image_detail=image_detail
+        )
+
+        if initialize:
+            self.initialize_genai(ai_platform=self.ai_platform)
+
+    def initialize_genai(self, ai_platform: AIPlatform = None):
+        """
+        Initialize the OpenAI client with platform-specific configuration.
+
+        Args:
+            ai_platform: AIPlatform configuration object
+        """
+        if not ai_platform:
+            raise ValueError("AI platform not specified")
+
+        if not ai_platform.base_url:
+            raise ValueError("Base URL is required")
+
+        # Initialize OpenAI client with platform-specific settings
+        self.client = OpenAI(
+            base_url=ai_platform.base_url,
+            api_key=ai_platform.api_key or "default"
+        )
+
+        self.ai_platform = ai_platform
+
+    def generate_ai_response(self, instructions: str, image_paths: list):
+        """
+        Generate AI response for test automation assertions with images.
+
+        Args:
+            instructions: Test assertion instructions
+            image_paths: List of image file paths to analyze
+
+        Returns:
+            AI-generated response
+        """
+        prompt = self._prepare_prompt(instructions, image_paths)
+        return self.chat_completion(prompt)
+
+    def chat_completion(self, messages):
+        """
+        Execute chat completion request.
+
+        Args:
+            messages: List of message dictionaries in OpenAI format
+
+        Returns:
+            Response content (simplified or full based on simple_response setting)
+        """
+        if not self.client:
+            raise RuntimeError("GenAI client not initialized. Call initialize_genai() first.")
+
+        # Convert messages format if needed (handle custom image format)
+        formatted_messages = self._format_messages_for_openai(messages)
+
+        try:
+            response = self.client.chat.completions.create(
+                model=self.ai_platform.model,
+                messages=formatted_messages
+            )
+
+            if self.simple_response:
+                return response.choices[0].message.content
+            else:
+                return response
+
+        except Exception as e:
+            raise Exception(f"Error during chat completion: {str(e)}")
+
+    def _prepare_prompt(self, instruction: str, image_paths: list = None):
+        """
+        Prepare prompt with instructions and images for test automation.
+
+        Args:
+            instruction: Test instruction/assertion
+            image_paths: List of image file paths
+
+        Returns:
+            Formatted prompt as list of messages
+        """
+        content = [
+            {
+                "type": "text",
+                "text": self.system_prompt
+            },
+            {
+                "type": "text",
+                "text": instruction
+            }
+        ]
+
+        # Add images if vision is supported
+        if image_paths and self.ai_platform.supports_vision:
+            for img_path in image_paths:
+                if not os.path.isfile(img_path):
+                    raise FileNotFoundError(f"Image not found: {img_path}")
+
+                content.append({
+                    "type": "image",
+                    "image_path": img_path
+                })
+
+        return [{"role": "user", "content": content}]
+
+    def _format_messages_for_openai(self, messages):
+        """
+        Convert custom message format to OpenAI-compatible format.
+        Handles image paths by converting them to base64 data URIs.
+
+        Args:
+            messages: List of messages in custom format
+
+        Returns:
+            List of messages in OpenAI format
+        """
+        formatted_messages = []
+
+        for message in messages:
+            formatted_content = []
+
+            for item in message.get("content", []):
+                if item.get("type") == "image":
+                    # Convert image file to base64 data URI
+                    image_path = item.get("image_path")
+                    if image_path and self.ai_platform.supports_vision:
+                        image_data = self._encode_image_to_base64(image_path)
+                        formatted_content.append({
+                            "type": "image_url",
+                            "image_url": {
+                                "url": image_data,
+                                "detail": self.ai_platform.detail
+                            }
+                        })
+                elif item.get("type") == "text":
+                    formatted_content.append({
+                        "type": "text",
+                        "text": item.get("text", "")
+                    })
+
+            formatted_messages.append({
+                "role": message.get("role"),
+                "content": formatted_content
+            })
+
+        return formatted_messages
+
+    @staticmethod
+    def _encode_image_to_base64(image_path: str) -> str:
+        """
+        Encode image file to base64 data URI.
+
+        Args:
+            image_path: Path to image file
+
+        Returns:
+            Base64-encoded data URI string
+        """
+        with open(image_path, "rb") as image_file:
+            image_data = base64.b64encode(image_file.read()).decode('utf-8')
+
+        # Detect image format from file extension
+        ext = os.path.splitext(image_path)[1].lower()
+        mime_types = {
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.gif': 'image/gif',
+            '.webp': 'image/webp'
+        }
+        mime_type = mime_types.get(ext, 'image/png')
+
+        return f"data:{mime_type};base64,{image_data}"
+
+    @staticmethod
+    def extract_result_and_explanation_from_response(response: str):
+        """
+        Extract RESULT and EXPLANATION from formatted response.
+
+        Args:
+            response: AI response string
+
+        Returns:
+            Tuple of (result, explanation)
+        """
+        parts = response.split("RESULT:", 1)
+        if len(parts) < 2:
+            return "fail", response
+
+        result_and_explanation = parts[1].strip()
+
+        parts = result_and_explanation.split("EXPLANATION:", 1)
+        if len(parts) < 2:
+            return parts[0].strip(), response
+
+        result = parts[0].strip()
+        explanation = parts[1].strip()
+
+        return result, explanation

AIVision/library.py

@@ -0,0 +1,437 @@
+# MIT License
+#
+# Copyright (c) 2025 Róbert Malovec
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from .genai import GenAI
+from .genai import Platforms
+from PIL import Image, ImageDraw, ImageFont
+from robot.api.deco import keyword
+from robot.api import logger
+from robot.libraries.BuiltIn import BuiltIn, RobotNotRunningError
+from datetime import datetime
+import os
+
+"""
+GenAI Testing library module for Robot Framework
+"""
+
+
+def _get_rf_output_dir():
+    """Returns Robot Framework output directory path"""
+    try:
+        output_dir = BuiltIn().get_variable_value("${OUTPUT_DIR}")
+    except RobotNotRunningError:
+        output_dir = os.getcwd()
+
+    return output_dir
+
+
+class AIVision:
+    """
+    AI Vision Library module for Robot Framework
+
+    This RF library provides GenAI enabled front-end, UI and visual templates testing capabilities
+
+    """
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+    FONT = os.path.join(
+        os.path.dirname(os.path.realpath(__file__)), "font", "Anton-Regular.ttf"
+    )
+    OUTPUT_DIR = _get_rf_output_dir()
+
+    def __init__(self, base_url: str = None, api_key: str = None, platform: Platforms = Platforms.Ollama,
+                 model: str = None, image_detail: str = None, simple_response: bool = True,
+                 initialize: bool = True, system_prompt: str = None):
+
+        self.genai = GenAI(base_url=base_url, api_key=api_key, platform=platform,
+                           model=model, image_detail=image_detail,
+                           simple_response=simple_response, initialize=initialize, system_prompt=system_prompt)
+
+    @keyword
+    def verify_that(self, screenshot_paths, instructions):
+        """Verifies that the image matches the instructions
+
+        Input parameters:
+
+        ``image_path``: (required) Path(s) to the image. Can be a single path or a list of paths
+
+        ``instructions``: (required) Instructions to be verified
+
+        *Examples*:
+
+        | Verify That | /path/to/image.png | Contains green logo in top right corner |
+
+        | @{img_paths}  = | Create List | /path/to/image1.png | /path/to/image2.png |
+        | Verify That | ${img_paths} | First image contains logo as referenced on 2nd image. |
+        """
+        screenshot_paths = [screenshot_paths] if isinstance(screenshot_paths, str) else screenshot_paths
+        response = self.genai.generate_ai_response(instructions=f"Verify that: {instructions}", image_paths=screenshot_paths)
+        logger.debug(response)
+
+        self._assert_result(response)
+
+    @keyword
+    def verify_screenshot_matches_look_and_feel_template(self, screenshot_path, template_path,
+                                                         override_instructions: str = None,
+                                                         create_combined_image: bool = True):
+        """Verifies that the screenshot matches the look and feel template
+
+        Input parameters:
+
+        ``screenshot_path``: (required) Path to the screenshot image
+
+        ``template_path``: (required) Path to the template image
+
+        ``override_instructions``: (optional) If specified, it will override the built-in assertion instructions
+
+        ``create_combined_image``: (optional) default is _True_. If _True_, combined image will be created and saved
+
+        _Return Value_ is the path of the saved image
+
+        *Examples*:
+        | Verify Screenshot Matches Look And Feel Template | /path/to/screenshot.png | /path/to/template.png |
+        | Verify Screenshot Matches Look And Feel Template | /path/to/screenshot.png | /path/to/template.png | override_instructions=Custom instructions |
+        """
+        if create_combined_image:
+            try:
+                self.combine_images_on_paths_side_by_side(screenshot_path, template_path, "Actual", "Expected",
+                                                          save=True)
+            except Exception as e:
+                logger.warn(f"Could not create combined image: {e}")
+
+        instructions = """First image is showing actual application view.
+Second image is reference design template. 
+Verify screenshot matches look and feel template. Pay attention to details, design is important.
+Make sure to check also all the visible logos, titles, labels, spelling, texts, links, menus, banners
+and any available graphics. Always doublecheck the reference image in case you think some
+text, label, logo or element is overlapping or containing typo.
+"""
+        if override_instructions:
+            instructions = override_instructions
+        response = self.genai.generate_ai_response(
+            instructions=instructions,
+            image_paths=[screenshot_path, template_path])
+
+        self._assert_result(response)
+
+    @staticmethod
+    @keyword
+    def open_image(image_path, mode="RGB"):
+        """Opens image from provided path
+
+        Input parameters:
+
+        ``image_path``: (required) Path to the image
+
+        ``mode``: (optional) default is _RGB_.
+                  Defines type and depth of a pixel to which the opened image will be converted.
+                  Supported modes can be seen
+                  [https://pillow.readthedocs.io/en/3.0.x/handbook/concepts.html#modes|here].
+
+        _Return value_ is the PIL Image object
+
+        *Example*:
+        | ${image} = | Open Image | /path/to/image.png |
+        | ${image} = | Open Image | /path/to/image.png | RGBA |
+        """
+
+        try:
+            image = Image.open(image_path)
+            logger.debug(f"Image '{image_path}' was opened successfully")
+        except Exception as err:
+            raise AssertionError(
+                f"Could not open image on provided path:\n{type(err).__name__}: {err}"
+            )
+
+        if image.mode != mode:
+            logger.debug(
+                f"Image is in mode '{image.mode}' but desired is '{mode}'. Starting conversion."
+            )
+            try:
+                image = image.convert(mode=mode)
+                logger.debug(f"Image successfully converted to mode '{mode}'")
+            except Exception as err:
+                raise AssertionError(
+                    f"Could not convert image to provided mode:\n{type(err).__name__}: {err}"
+                )
+
+        return image
+
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    @keyword
+    def save_image(
+            self,
+            image,
+            image_name=None,
+            image_format=None,
+            watermark=None,
+            image_path=OUTPUT_DIR,
+    ):
+        """Saves image to provided path and name
+
+        Input parameters:
+
+        ``image``: (required) PIL image object to save
+
+        ``image_name``: (optional) Name of the image.
+                        If empty image name will be auto-generated
+
+        ``image_format``: (optional) If not set the image format will be determined from the _image_name_ extension
+                          if specified there
+
+        ``watermark``: (optional) If the specified image will be watermarked with the specified string in top left corner
+
+        ``image_path``: (optional) Path to image to save.
+                        If not specified images are being stored to the Robot Framework output directory
+
+        _Return Value_: Path of the saved image
+
+        *Examples*:
+        | Save Image | ${image}| my_image.png |
+        | Save Image | ${image}| my_image | png |
+        | Save Image | ${image}| my_image.png | watermark=My Label |
+        | Save Image | ${image}| my_image.png | image_path=/path/to/my/image/directory |
+        """
+        try:
+            if not image_name:
+                if image_format:
+                    image_name = self.generate_image_name(extension=image_format)
+                else:
+                    image_name = self.generate_image_name()
+
+            dest = os.path.join(image_path, image_name)
+
+            if image_format:
+                dest = os.path.join(dest, ".", image_format.lower())
+
+            logger.debug(f"Image will be saved to '{dest}'")
+
+            if watermark:
+                logger.debug(f"Adding watermark '{watermark}' to image")
+                image = self.add_watermark_to_image(image, watermark)
+
+            image.save(dest)
+
+        except Exception as err:
+            raise AssertionError(f"Could not save image:\n{type(err).__name__}: {err}")
+
+        logger.info(
+            f"<img width='800' src='{os.path.relpath(dest, image_path)}'/>", html=True
+        )
+
+        return dest
+
+    @staticmethod
+    @keyword
+    def generate_image_name(prefix="Snap", extension="png"):
+        """Generates unique image name with the specified prefix and optional image extension
+
+        Input parameters:
+
+        ``prefix``: (optional) default is "Image"
+
+        ``extension``: (optional) default is _png_
+
+        _Return Value_ is generated string representing unique image name
+
+        *Examples*:
+        | ${img_name} = | Generate Image Name |
+        | ${img_name} = | Generate Image Name | My-Image |
+        | ${img_name} = | Generate Image Name | My-Image | jpg |
+        """
+        if not prefix:
+            prefix = ""
+            name_template = "%s%s"
+        else:
+            name_template = "%s-%s"
+
+        image_name = name_template % (
+            prefix,
+            datetime.now().strftime("%m-%d-%Y_%H-%M-%S-%f")[:-3],
+        )
+        if extension:
+            image_name = f"{image_name}.{extension.lower()}"
+
+        logger.debug(f"Generated image name is: {image_name}")
+
+        return image_name
+
+    @keyword
+    def combine_images_on_paths_side_by_side(self, image_path1, image_path2, watermark1=None, watermark2=None,
+                                             mode="RGB", save=True):
+        """Combines two images specified by file path to one big image side-by-side
+
+        Input parameters:
+
+        ``image_path1``: (required) Path to the first image
+
+        ``image_path2``: (required) Path to the second image
+
+        ``watermark1``: (optional) If specified image1 will be watermarked with the specified string in top left corner
+
+        ``watermark2``: (optional) If specified image2 will be watermarked with the specified string in top left corner
+
+        ``mode``: (optional) default is _RGB_.
+
+        _Return Value_ is combined image as PIL Image format
+
+        *Examples*:
+        | ${image} = | Combine Images On Paths Side By Side | /path/to/image1.png | /path/to/image2.png |
+        | ${image} = | Combine Images On Paths Side By Side | /path/to/image1.png | /path/to/image2.png | Expected | Actual |
+
+        """
+        img1 = self.open_image(image_path1, mode=mode)
+        img2 = self.open_image(image_path2, mode=mode)
+
+        combined_img = self.combine_images_side_by_side(img1, img2, watermark1=watermark1, watermark2=watermark2,
+                                                        mode=mode)
+
+        if save:
+            self.save_image(combined_img)
+
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    @keyword
+    def combine_images_side_by_side(
+            self, image1, image2, watermark1=None, watermark2=None, mode="RGB"
+    ):
+        """Combines two images to one big image side-by-side
+
+        Input parameters:
+
+        ``image1``: (required) Image one (PIL Image object) to combine
+
+        ``image2``: (required) Image two (PIL Image object) to combine
+
+        ``watermark1``: (optional) If specified image1 will be watermarked with the specified string in top left corner
+
+        ``watermark2``: (optional) If specified image2 will be watermarked with the specified string in top left corner
+
+        ``mode``: (optional) default is _RGB_.
+                  Defines type and depth of a pixel which will be used for watermark layer.
+                  You do not need typically change this value.
+                  Supported modes can be seen
+                  [https://pillow.readthedocs.io/en/3.0.x/handbook/concepts.html#modes|here].
+
+        _Return Value_ is combined image as PIL Image format
+
+        *Examples*:
+        | ${image} = | Combine Images Side By Side | ${image1} | ${image2} |
+        | ${image} = | Combine Images Side By Side | ${image1} | ${image2} |RGBA |
+        """
+        try:
+            # Create empty image for both images to fit
+            combined_image = Image.new(
+                mode,
+                (
+                    image1.size[0] + image2.size[0] + 1,
+                    max(image1.size[1], image2.size[1]),
+                ),
+            )
+
+            if watermark1:
+                logger.debug(f"Adding watermark '{watermark1}' to image1")
+                image1 = self.add_watermark_to_image(image1, watermark1)
+
+            if watermark2:
+                logger.debug(f"Adding watermark '{watermark2}' to image2")
+                image2 = self.add_watermark_to_image(image2, watermark2)
+
+            # Concatenate both images to one big image
+            combined_image.paste(image1, (0, 0))
+            combined_image.paste(image2, (image1.size[0] + 1, 0))
+
+        except Exception as err:
+            raise AssertionError(
+                f"Could not create combined image:\n{type(err).__name__}: {err}"
+            )
+
+        return combined_image
+
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    @keyword
+    def add_watermark_to_image(
+            self, image, text, color="red", text_size=50, text_position=(0, 0), mode="RGB"
+    ):
+        """Adds watermark text to the image
+
+        Input parameters:
+
+        ``image``: (required) PIL image object to add watermark to
+
+        ``text``: (required) Text string which will be added to the image
+
+        ``color``: (optional) default is _red_.
+                   Text color of the watermark
+
+        ``text_size``: (optional) default is _50_.
+                       Text size of the watermark
+
+        ``text_position``: (optional) default is _(0, 0)_.
+                           Represents X,Y coordinates in the image where to add watermark
+
+        ``mode``: (optional) default is _RGB_.
+                  Defines type and depth of a pixel which will be used for watermark layer.
+                  You do not need typically change this value.
+                  Supported modes can be seen
+                  [https://pillow.readthedocs.io/en/3.0.x/handbook/concepts.html#modes|here].
+
+        _Return Value_ represents PIL Image object
+
+        *Examples*:
+        | ${w_image} = | Add Watermark To Image | ${image} | Original |
+        | ${w_image} = | Add Watermark To Image | ${image} | Original | blue |
+        | ${w_image} = | Add Watermark To Image | ${image} | text=Original | color=blue |
+        """
+        font_path = self.FONT
+
+        try:
+            font = ImageFont.truetype(font_path, text_size)
+        except Exception as err:
+            raise AssertionError(
+                f"Could not set watermark font:\n{type(err).__name__}: {err}"
+            )
+
+        try:
+            # Create watermark drawing canvas object
+            watermark = Image.new(mode, image.size)
+            draw = ImageDraw.ImageDraw(watermark, mode)
+
+            # Create semi-transparent watermark text
+            draw.text(text_position, text, fill=color, font=font)
+            mask = watermark.convert("L").point(lambda x: min(x, 100))
+            watermark.putalpha(mask)
+
+            # Create new image with watermark
+            w_image = image.copy()
+            w_image.paste(watermark, None, watermark)
+        except Exception as err:
+            raise AssertionError(
+                f"Could not create watermark:\n{type(err).__name__}: {err}"
+            )
+
+        return w_image
+
+    def _assert_result(self, response):
+        result, explanation = self.genai.extract_result_and_explanation_from_response(response)
+        if result and result.lower() == "pass":
+            logger.info(f"Verification passed:\n{explanation}")
+        else:
+            raise AssertionError(f"Verification failed:\n{explanation}")

AIVision/platforms.py

@@ -0,0 +1,68 @@
+# MIT License
+#
+# Copyright (c) 2025 Róbert Malovec
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from enum import Enum
+
+
+class Platforms(Enum):
+    """Enum defining supported AI platforms with their default configurations."""
+    Ollama = {
+        "default_model": "qwen3-coder:480b-cloud",
+        "default_base_url": "http://localhost:11434/v1",
+        "api_key_required": False,
+        "supports_vision": True
+    }
+
+    DockerModel = {
+        "default_model": "ai/qwen3-vl:8B-Q8_K_XL",
+        "default_base_url": "http://localhost:12434/engines/v1",
+        "api_key_required": False,
+        "supports_vision": True
+    }
+
+    OpenAI = {
+        "default_model": "gpt-5.2",
+        "default_base_url": "https://api.openai.com/v1",
+        "api_key_required": True,
+        "supports_vision": True
+    }
+
+    Perplexity = {
+        "default_model": "sonar-pro",
+        "default_base_url": "https://api.perplexity.ai",
+        "api_key_required": True,
+        "supports_vision": True
+    }
+
+    Gemini = {
+        "default_model": "gemini-2.5-flash",
+        "default_base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
+        "api_key_required": True,
+        "supports_vision": True
+    }
+
+    Manual = {
+        "default_model": None,
+        "default_base_url": None,
+        "api_key_required": True,
+        "supports_vision": True
+    }

robotframework_aivision-0.2.0a1.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: robotframework_aivision
+Version: 0.2.0a1
+Summary: AI Vision library for Robot Framework
+Home-page: https://github.com/robco/robotframework-aivision.git
+Author: Róbert Malovec
+Author-email: robert@malovec.sk
+License: MIT License
+        
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE.txt
+Requires-Dist: robotframework
+Requires-Dist: pillow
+Requires-Dist: openai
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/robco)
+# Robot Framework AI Vision Library
+
+AI VIsion Library for Robot Framework that verifies UI/screenshots (including template “look & feel”) by sending instructions plus one or more images to an OpenAI-compatible API (Ollama, OpenAI, Perplexity, Gemini, etc.).
+
+The main keyword (`Verify That`) expects the model to return a strict `RESULT:` / `EXPLANATION:` format and will fail the test if the result is not `pass`.
+
+## Features
+
+- Visual assertions on one or more screenshots using natural-language instructions.
+- Template comparison keyword to validate “actual vs expected” look & feel (optionally creates a side-by-side image).
+- Image utilities built on Pillow: open/convert, watermark, combine images, auto-generate names, save into Robot Framework output directory.
+- Works with multiple providers via the `openai` Python client and OpenAI-compatible endpoints (`base_url`).
+
+## Installation
+
+**Install from PyPI (once published):**
+```bash
+pip install -U robotframework-aivision
+```
+
+Runtime dependencies include Robot Framework, Pillow, and the `openai` Python client.
+
+## Configuration
+
+Import the library in Robot Framework and choose a provider using `platform` plus optional overrides (`base_url`, `api_key`, `model`, `image_detail`).
+
+### Robot Framework import examples
+
+**Default (Ollama-like local setup):**
+```robotframework
+*** Settings ***
+Library  AIVision
+```
+
+**OpenAI (API key required):**
+```robotframework
+*** Settings ***
+Library  AIVision
+... platform=OpenAI
+... api_key=%{OPENAI_API_KEY}
+... model=gpt-5.2
+```
+
+**Perplexity:**
+```robotframework
+*** Settings ***
+Library  AIVision
+... platform=Perplexity
+... api_key=%{PPLX_API_KEY}
+... model=sonar-pro
+```
+
+**Gemini (OpenAI-compatible endpoint):**
+```robotframework
+*** Settings ***
+Library  AIVision
+... platform=Gemini
+... api_key=%{GEMINI_API_KEY}
+... model=gemini-2.5-flash
+```
+
+### Supported platforms (defaults)
+
+The library defines these platform presets (model and `base_url`) which you can override via import arguments.
+
+| Platform | Default `base_url` | Default model | API key |
+|---|---|---|---|
+| Ollama | `http://localhost:11434/v1` | `qwen3-coder:480b-cloud` | Not required |
+| DockerModel | `http://localhost:12434/engines/v1` | `ai/qwen3-vl:8B-Q8_K_XL` | Not required. |
+| OpenAI | `https://api.openai.com/v1` | `gpt-5.2` | Required. |
+| Perplexity | `https://api.perplexity.ai` | `sonar-pro` | Required. |
+| Gemini | `https://generativelanguage.googleapis.com/v1beta/openai/` | `gemini-2.5-flash` | Required. |
+| Manual | `None` | `None` | Required. |
+
+## Keywords
+
+All keywords below are implemented in `AIVision` and are available after importing the library.
+
+| Keyword | Purpose |
+|---|---|
+| `Verify That` | Send one or more screenshots + instructions to the model, parse the `RESULT` and raise `AssertionError` on failure. |
+| `Verify Screenshot Matches Look And Feel Template` | Compare a screenshot against a reference template with a built-in instruction set; optional combined image creation. |
+| `Open Image` | Open an image (and optionally convert mode, default `RGB`). |
+| `Save Image` | Save a PIL image to a path (defaults to RF output directory) with optional watermark. |
+| `Generate Image Name` | Create a unique timestamp-based filename with prefix/extension. |
+| `Combine Images On Paths Side By Side` | Combine two image files side-by-side (optionally watermark) and optionally save. |
+| `Combine Images Side By Side` | Combine two in-memory PIL images side-by-side (optionally watermark). |
+| `Add Watermark To Image` | Add watermark text using the included font file. |
+
+## Usage examples
+
+### Simple visual assertion
+
+```robotframework
+*** Settings ***
+Library  AIVision  platform=Ollama
+
+*** Test Cases ***
+Login button is correct
+   Verify That  ${CURDIR}/screens/login.png  Login button is visible and labeled as 'Sign In'
+```
+
+### Compare screenshot to design template
+
+```robotframework
+*** Settings ***
+Library  AIVision
+
+*** Test Cases ***
+Home page matches template
+   Verify Screenshot Matches Look And Feel Template
+   ...  ${CURDIR}/screens/home_actual.png
+   ...  ${CURDIR}/templates/home_expected.png
+```
+
+### Override template instructions
+
+```robotframework
+*** Settings ***
+Library  AIVision
+
+*** Test Cases ***
+Home page matches template - custom rules
+   Verify Screenshot Matches Look And Feel Template
+   ...  ${CURDIR}/screens/home_actual.png
+   ...  ${CURDIR}/templates/home_expected.png
+   ...  override_instructions=Verify layout, spacing, typography, and brand colors match the template exactly.
+```
+
+
+Version history
+----------------
+
+0.2.0a1, 2026-02-02 -- Alpha1 version
+0.2.0,   2026-01-29 -- AI System Prompt is configurable
+0.1.0,   2025-12-19 -- Additional GenAI Providers added
+0.0.1,   2024-05-11 -- Initial version

robotframework_aivision-0.2.0a1.dist-info/RECORD

@@ -0,0 +1,12 @@
+AIVision/__init__.py,sha256=Dp_ukmv2lgMOTdS-8xzUokr4IfC_aB91cGPfrinbHUA,1224
+AIVision/genai.py,sha256=Na_EYVSGkir_1xqdpJocG5MVZUw9tSc9CV0JBEwxdzY,11678
+AIVision/library.py,sha256=MZ-JDEC6rsuUuVscIijDtJcYgiiZEARdI94b_qLQ8Wc,16952
+AIVision/platforms.py,sha256=vuozdhmHrhLlM85z4mHTlCiY2STvU_cgDyc0XD441vs,2388
+AIVision/font/Anton-Regular.ttf,sha256=wkY8RDEDa8ak_mppboCdPAo9E3Md1h08n4wD9GYHpjE,161212
+AIVision/font/OFL.txt,sha256=7mfm7iJ5C3kp8aN2nKKAHVZcZLWpCWlCwa31WW3pyeQ,4484
+robotframework_aivision-0.2.0a1.dist-info/licenses/LICENSE,sha256=GnlimnQtg17QJ712UYWtmfPQFsme_q4cUxAO79yvkZ0,1072
+robotframework_aivision-0.2.0a1.dist-info/licenses/LICENSE.txt,sha256=GnlimnQtg17QJ712UYWtmfPQFsme_q4cUxAO79yvkZ0,1072
+robotframework_aivision-0.2.0a1.dist-info/METADATA,sha256=h0OhQJw3O_xFkLPf4IipgujylcwZSgXN-MvVydsAw4E,5529
+robotframework_aivision-0.2.0a1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+robotframework_aivision-0.2.0a1.dist-info/top_level.txt,sha256=Z-P4V4dmnDuQoeciyqyQzGjkPLxcj924T4zKr5fNEuk,9
+robotframework_aivision-0.2.0a1.dist-info/RECORD,,

robotframework_aivision-0.2.0a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

robotframework_aivision-0.2.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Róbert Malovec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

robotframework_aivision-0.2.0a1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Róbert Malovec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

robotframework_aivision-0.2.0a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+AIVision