robotframework-gemini 0.2.0__tar.gz

robotframework_gemini-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+/dist/
+/*.egg-info/
+/.pytest_cache/

robotframework_gemini-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Nizolli
+
+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_gemini-0.2.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: robotframework-gemini
+Version: 0.2.0
+Summary: Google Gemini oracles for Robot Framework: text-only and multimodal (image) assertions.
+Project-URL: Homepage, https://github.com/carlosnizolli/robotframework-gemini
+Project-URL: Documentation, https://github.com/carlosnizolli/robotframework-gemini#readme
+Project-URL: Repository, https://github.com/carlosnizolli/robotframework-gemini
+Project-URL: Issues, https://github.com/carlosnizolli/robotframework-gemini/issues
+Project-URL: Changelog, https://github.com/carlosnizolli/robotframework-gemini/releases
+Author: Carlos Nizolli
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Gemini,LLM,QA,Robot Framework,multimodal,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Robot Framework
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: google-genai>=1.10.0
+Provides-Extra: browser
+Requires-Dist: robotframework-browser>=18.0.0; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# robotframework-gemini
+
+Biblioteca **Python** e **keywords do Robot Framework** para oráculos com **Google Gemini**: avaliação **só texto** (API, logs, JSON, etc.) ou **multimodal** com imagem (arquivo PNG ou captura do **Robot Framework Browser**).
+
+- **Multimodal**: envia o texto do prompt e a captura como `Part` em bytes (`google-genai`).
+- **Fluxo recomendado**: duas entradas — **contexto** (enquadramento do teste) e **avaliação** (critério ou pergunta objetiva).
+- **Browser opcional**: keywords de screenshot exigem `Library    Browser`; keywords de texto funcionam sem navegador.
+
+## Instalação
+
+```bash
+pip install robotframework-gemini
+```
+
+Com suporte a captura via Robot Framework Browser (Playwright):
+
+```bash
+pip install "robotframework-gemini[browser]"
+python -m pip install robotframework
+```
+
+Desenvolvimento local:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Variáveis de ambiente
+
+| Variável          | Função                                      |
+|-------------------|---------------------------------------------|
+| `GEMINI_API_KEY`  | Chave da API Gemini (obrigatória se não passar `api_key` na Library) |
+| `GEMINI_MODEL`    | Modelo (ex.: `gemini-2.0-flash`). Se omitido, usa `gemini-2.0-flash`. |
+
+## Uso em Python (`GeminiOrchestrator`)
+
+```python
+from pathlib import Path
+from robotframework_gemini import GeminiOrchestrator
+
+orc = GeminiOrchestrator()
+ctx = "Web dashboard with the 'Active' category filter applied."
+crit = "Do the visible list items match the selected category?"
+raw = orc.evaluate_with_image(ctx, crit, Path("screen.png"))
+```
+
+Para formato de saída restrito (ex.: Yes/No), use `extra_instructions`:
+
+```python
+raw = orc.evaluate_with_text(
+    ctx,
+    crit,
+    extra_instructions="Reply with one word only: Yes or No.",
+)
+```
+
+## Uso no Robot Framework
+
+### Só texto (sem Browser)
+
+```robot
+*** Settings ***
+Library    GeminiLibrary
+
+*** Keywords ***
+Validar resposta da API
+    ${ctx}=       Set Variable    {"status": "ok", "items": 3}
+    ${crit}=      Set Variable    O payload indica sucesso com itens?
+    ${raw}=       Gemini Evaluate Text    ${ctx}    ${crit}
+    Log    ${raw}
+```
+
+### Com captura de tela (Browser)
+
+Declare a biblioteca **Browser** antes de **Gemini**:
+
+```robot
+*** Settings ***
+Library    Browser
+Library    GeminiLibrary
+
+*** Keywords ***
+Checar tela por critério neutro
+    ${ctx}=       Set Variable    Lista filtrada por status Ativo.
+    ${crit}=      Set Variable    Todos os itens visíveis mostram status Ativo?
+    ${raw}=       Gemini Evaluate With Screen    ${ctx}    ${crit}
+    Log    ${raw}
+```
+
+Import explícito (equivalente):
+
+```robot
+Library    robotframework_gemini.library.GeminiLibrary
+```
+
+Com arquivo já salvo:
+
+```robot
+Browser.Take Screenshot    ${OUTPUT_DIR}/tela.png
+${raw}=    Gemini Evaluate With Image File    ${ctx}    ${crit}    ${OUTPUT_DIR}/tela.png
+```
+
+Veredito via prompt (primeira linha) e nota 1–5:
+
+```robot
+${raw}=    Gemini Evaluate With Screen    ${ctx}    ${crit}
+...    extra_instructions=Responda com uma palavra na primeira linha: Sim ou Não.
+${v}=    Get Line    ${raw}    0
+Should Be Equal As Strings    ${v}    Sim
+
+${raw}=    Gemini Evaluate Text Rating    ${ctx}    ${criterion}
+${score}=    Gemini Parse Rating    ${raw}
+```
+
+Consulte também [`examples/demo_template.robot`](examples/demo_template.robot).
+
+## Documentação de Keywords
+
+- Português: [`docs/KEYWORDS.pt-BR.md`](docs/KEYWORDS.pt-BR.md)
+- English: [`docs/KEYWORDS.en.md`](docs/KEYWORDS.en.md)
+
+## Compatibilidade
+
+- `BrowserGeminiLibrary` permanece como alias de `GeminiLibrary` para suítes existentes.
+- Variáveis legadas (`LLM_API_KEY`, `LLM_API_KEY_LIA`, `LLM_LIA_MODEL`) são mapeadas para `GEMINI_*` ao importar o pacote.
+
+## Testes
+
+```bash
+pytest
+```
+
+Os testes usam mocks de `generate_content`; não há chamadas reais à API.
+
+## Licença
+
+MIT.

robotframework_gemini-0.2.0/README.md

@@ -0,0 +1,137 @@
+# robotframework-gemini
+
+Biblioteca **Python** e **keywords do Robot Framework** para oráculos com **Google Gemini**: avaliação **só texto** (API, logs, JSON, etc.) ou **multimodal** com imagem (arquivo PNG ou captura do **Robot Framework Browser**).
+
+- **Multimodal**: envia o texto do prompt e a captura como `Part` em bytes (`google-genai`).
+- **Fluxo recomendado**: duas entradas — **contexto** (enquadramento do teste) e **avaliação** (critério ou pergunta objetiva).
+- **Browser opcional**: keywords de screenshot exigem `Library    Browser`; keywords de texto funcionam sem navegador.
+
+## Instalação
+
+```bash
+pip install robotframework-gemini
+```
+
+Com suporte a captura via Robot Framework Browser (Playwright):
+
+```bash
+pip install "robotframework-gemini[browser]"
+python -m pip install robotframework
+```
+
+Desenvolvimento local:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Variáveis de ambiente
+
+| Variável          | Função                                      |
+|-------------------|---------------------------------------------|
+| `GEMINI_API_KEY`  | Chave da API Gemini (obrigatória se não passar `api_key` na Library) |
+| `GEMINI_MODEL`    | Modelo (ex.: `gemini-2.0-flash`). Se omitido, usa `gemini-2.0-flash`. |
+
+## Uso em Python (`GeminiOrchestrator`)
+
+```python
+from pathlib import Path
+from robotframework_gemini import GeminiOrchestrator
+
+orc = GeminiOrchestrator()
+ctx = "Web dashboard with the 'Active' category filter applied."
+crit = "Do the visible list items match the selected category?"
+raw = orc.evaluate_with_image(ctx, crit, Path("screen.png"))
+```
+
+Para formato de saída restrito (ex.: Yes/No), use `extra_instructions`:
+
+```python
+raw = orc.evaluate_with_text(
+    ctx,
+    crit,
+    extra_instructions="Reply with one word only: Yes or No.",
+)
+```
+
+## Uso no Robot Framework
+
+### Só texto (sem Browser)
+
+```robot
+*** Settings ***
+Library    GeminiLibrary
+
+*** Keywords ***
+Validar resposta da API
+    ${ctx}=       Set Variable    {"status": "ok", "items": 3}
+    ${crit}=      Set Variable    O payload indica sucesso com itens?
+    ${raw}=       Gemini Evaluate Text    ${ctx}    ${crit}
+    Log    ${raw}
+```
+
+### Com captura de tela (Browser)
+
+Declare a biblioteca **Browser** antes de **Gemini**:
+
+```robot
+*** Settings ***
+Library    Browser
+Library    GeminiLibrary
+
+*** Keywords ***
+Checar tela por critério neutro
+    ${ctx}=       Set Variable    Lista filtrada por status Ativo.
+    ${crit}=      Set Variable    Todos os itens visíveis mostram status Ativo?
+    ${raw}=       Gemini Evaluate With Screen    ${ctx}    ${crit}
+    Log    ${raw}
+```
+
+Import explícito (equivalente):
+
+```robot
+Library    robotframework_gemini.library.GeminiLibrary
+```
+
+Com arquivo já salvo:
+
+```robot
+Browser.Take Screenshot    ${OUTPUT_DIR}/tela.png
+${raw}=    Gemini Evaluate With Image File    ${ctx}    ${crit}    ${OUTPUT_DIR}/tela.png
+```
+
+Veredito via prompt (primeira linha) e nota 1–5:
+
+```robot
+${raw}=    Gemini Evaluate With Screen    ${ctx}    ${crit}
+...    extra_instructions=Responda com uma palavra na primeira linha: Sim ou Não.
+${v}=    Get Line    ${raw}    0
+Should Be Equal As Strings    ${v}    Sim
+
+${raw}=    Gemini Evaluate Text Rating    ${ctx}    ${criterion}
+${score}=    Gemini Parse Rating    ${raw}
+```
+
+Consulte também [`examples/demo_template.robot`](examples/demo_template.robot).
+
+## Documentação de Keywords
+
+- Português: [`docs/KEYWORDS.pt-BR.md`](docs/KEYWORDS.pt-BR.md)
+- English: [`docs/KEYWORDS.en.md`](docs/KEYWORDS.en.md)
+
+## Compatibilidade
+
+- `BrowserGeminiLibrary` permanece como alias de `GeminiLibrary` para suítes existentes.
+- Variáveis legadas (`LLM_API_KEY`, `LLM_API_KEY_LIA`, `LLM_LIA_MODEL`) são mapeadas para `GEMINI_*` ao importar o pacote.
+
+## Testes
+
+```bash
+pytest
+```
+
+Os testes usam mocks de `generate_content`; não há chamadas reais à API.
+
+## Licença
+
+MIT.

robotframework_gemini-0.2.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "robotframework-gemini"
+version = "0.2.0"
+description = "Google Gemini oracles for Robot Framework: text-only and multimodal (image) assertions."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Carlos Nizolli" }]
+keywords = ["Robot Framework", "Gemini", "LLM", "multimodal", "QA", "testing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Framework :: Robot Framework",
+]
+dependencies = [
+    "google-genai>=1.10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/carlosnizolli/robotframework-gemini"
+Documentation = "https://github.com/carlosnizolli/robotframework-gemini#readme"
+Repository = "https://github.com/carlosnizolli/robotframework-gemini"
+Issues = "https://github.com/carlosnizolli/robotframework-gemini/issues"
+Changelog = "https://github.com/carlosnizolli/robotframework-gemini/releases"
+
+[project.optional-dependencies]
+browser = [
+    "robotframework-browser>=18.0.0",
+]
+dev = [
+    "pytest>=8.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.entry-points."robotframework.libraries"]
+GeminiLibrary = "robotframework_gemini.library:GeminiLibrary"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/robotframework_gemini"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/robotframework_gemini",
+    "LICENSE",
+    "README.md",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

robotframework_gemini-0.2.0/src/robotframework_gemini/__init__.py

@@ -0,0 +1,21 @@
+"""Gemini-backed text and multimodal oracles for Robot Framework."""
+
+from robotframework_gemini.legacy_env import (
+    ensure_gemini_env_from_legacy,
+    ensure_importable,
+)
+
+ensure_importable()
+ensure_gemini_env_from_legacy()
+
+from robotframework_gemini.client import GeminiOrchestrator
+from robotframework_gemini.library import BrowserGeminiLibrary, GeminiLibrary
+
+__all__ = [
+    "GeminiOrchestrator",
+    "GeminiLibrary",
+    "BrowserGeminiLibrary",
+    "__version__",
+]
+
+__version__ = "0.2.0"

robotframework_gemini-0.2.0/src/robotframework_gemini/browser_helpers.py

@@ -0,0 +1,50 @@
+"""Capture screenshot / page source from an active Robot Framework Browser library."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def get_open_browser_library():
+    """Return the live Browser library instance (Playwright) from Robot BuiltIn."""
+    try:
+        from robot.libraries.BuiltIn import BuiltIn
+    except ImportError as e:
+        raise RuntimeError("robotframework-gemini: Robot Framework not available") from e
+
+    try:
+        return BuiltIn().get_library_instance("Browser")
+    except Exception as e:
+        raise RuntimeError(
+            "robotframework-gemini: Browser library is not open or not imported as 'Browser'"
+        ) from e
+
+
+def take_screenshot_to_path(
+    output_path: str | Path,
+    *,
+    selector: str | None = None,
+) -> str:
+    """
+    Call Browser.take_screenshot and return the path returned by the library.
+
+    `selector` matches Browser kwarg when capturing an element region.
+    """
+    browser = get_open_browser_library()
+    kw: dict[str, Any] = {"filename": str(output_path)}
+    if selector:
+        kw["selector"] = selector
+    path = browser.take_screenshot(**kw)
+    logger.debug("Screenshot written: %s", path)
+    return str(path)
+
+
+def get_page_source_text() -> str:
+    browser = get_open_browser_library()
+    if not hasattr(browser, "get_page_source"):
+        raise RuntimeError("Browser library has no get_page_source")
+    return browser.get_page_source()

robotframework_gemini-0.2.0/src/robotframework_gemini/client.py

@@ -0,0 +1,174 @@
+"""Gemini client: multimodal (image file) and text-only calls."""
+
+from __future__ import annotations
+
+import logging
+import mimetypes
+import os
+from pathlib import Path
+
+from google import genai
+from google.genai import types
+
+from robotframework_gemini.prompt_build import (
+    DEFAULT_RATING_OUTPUT_INSTRUCTIONS,
+    build_evaluation_prompt,
+    merge_extra_instructions,
+)
+from robotframework_gemini.response_parse import normalize_rating
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_IMAGE_MIME = "image/png"
+
+
+def _mime_for_path(path: Path) -> str:
+    mime, _ = mimetypes.guess_type(path.name)
+    return mime or _DEFAULT_IMAGE_MIME
+
+
+class GeminiOrchestrator:
+    """
+    Thin wrapper around google-genai for test oracles.
+
+    Environment:
+    - GEMINI_API_KEY for the API key (unless ``api_key`` is passed explicitly)
+    - GEMINI_MODEL for model id (e.g. gemini-2.0-flash); defaults to gemini-2.0-flash
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        model: str | None = None,
+    ):
+        key = api_key or os.environ.get("GEMINI_API_KEY")
+        if not key:
+            raise ValueError(
+                "Missing API key: set GEMINI_API_KEY (or pass api_key=...)"
+            )
+        self.model = model or os.environ.get("GEMINI_MODEL") or "gemini-2.0-flash"
+        self._client = genai.Client(api_key=key)
+
+    def generate_from_text(self, prompt: str) -> str:
+        response = self._client.models.generate_content(model=self.model, contents=prompt)
+        text = (response.text or "").strip()
+        logger.debug("generate_from_text chars=%s", len(text))
+        return text
+
+    def generate_with_image_file(self, prompt: str, image_path: str | Path) -> str:
+        path = Path(image_path)
+        if not path.is_file():
+            raise FileNotFoundError(f"Image not found: {path}")
+        data = path.read_bytes()
+        mime = _mime_for_path(path)
+        parts = [
+            types.Part.from_text(text=prompt),
+            types.Part.from_bytes(data=data, mime_type=mime),
+        ]
+        response = self._client.models.generate_content(
+            model=self.model,
+            contents=parts,
+        )
+        text = (response.text or "").strip()
+        logger.debug("generate_with_image_file chars=%s mime=%s", len(text), mime)
+        return text
+
+    def generate_with_image_and_html(
+        self,
+        prompt: str,
+        image_path: str | Path,
+        html_text: str,
+        *,
+        max_html_chars: int = 120_000,
+    ) -> str:
+        """Multimodal image + truncated HTML as additional text part."""
+        path = Path(image_path)
+        if not path.is_file():
+            raise FileNotFoundError(f"Image not found: {path}")
+        data = path.read_bytes()
+        mime = _mime_for_path(path)
+        html_snip = html_text[:max_html_chars] if html_text else ""
+        combined_prompt = f"{prompt}\n\n--- HTML (truncado) ---\n{html_snip}"
+        parts = [
+            types.Part.from_text(text=combined_prompt),
+            types.Part.from_bytes(data=data, mime_type=mime),
+        ]
+        response = self._client.models.generate_content(
+            model=self.model,
+            contents=parts,
+        )
+        return (response.text or "").strip()
+
+    def evaluate_with_image(
+        self,
+        context: str,
+        evaluation: str,
+        image_path: str | Path,
+        *,
+        extra_instructions: str | None = None,
+    ) -> str:
+        prompt = build_evaluation_prompt(
+            context,
+            evaluation,
+            extra_instructions=extra_instructions,
+            include_visual_focus=True,
+        )
+        return self.generate_with_image_file(prompt, image_path)
+
+    def evaluate_with_image_and_html(
+        self,
+        context: str,
+        evaluation: str,
+        image_path: str | Path,
+        html_text: str,
+        *,
+        extra_instructions: str | None = None,
+        max_html_chars: int = 120_000,
+    ) -> str:
+        prompt = build_evaluation_prompt(
+            context,
+            evaluation,
+            extra_instructions=extra_instructions,
+            include_visual_focus=True,
+        )
+        return self.generate_with_image_and_html(
+            prompt, image_path, html_text, max_html_chars=max_html_chars
+        )
+
+    def evaluate_with_text(
+        self,
+        context: str,
+        evaluation: str,
+        *,
+        extra_instructions: str | None = None,
+    ) -> str:
+        prompt = build_evaluation_prompt(
+            context,
+            evaluation,
+            extra_instructions=extra_instructions,
+            include_visual_focus=False,
+        )
+        return self.generate_from_text(prompt)
+
+    def evaluate_with_text_rating(
+        self,
+        context: str,
+        evaluation: str,
+        *,
+        extra_instructions: str | None = None,
+    ) -> str:
+        """Generic text-only judge: score how well ``context`` meets ``evaluation`` on a 1–5 scale."""
+        rating_extra = merge_extra_instructions(
+            DEFAULT_RATING_OUTPUT_INSTRUCTIONS,
+            extra_instructions,
+        )
+        return self.evaluate_with_text(
+            context,
+            evaluation,
+            extra_instructions=rating_extra,
+        )
+
+    @staticmethod
+    def parse_rating(raw: str) -> str:
+        return normalize_rating(raw)

robotframework_gemini-0.2.0/src/robotframework_gemini/legacy_env.py

@@ -0,0 +1,37 @@
+"""Map legacy QA env vars to GEMINI_* and ensure the package is importable in Docker mounts."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def ensure_importable() -> None:
+    """Add ``src/`` to ``sys.path`` when the package is not installed (repo volume mount)."""
+    try:
+        import robotframework_gemini.client  # noqa: F401
+        return
+    except ImportError:
+        pass
+    src = Path(__file__).resolve().parent.parent
+    src_str = str(src)
+    if src_str not in sys.path:
+        sys.path.insert(0, src_str)
+
+
+def ensure_gemini_env_from_legacy() -> None:
+    """
+  Set GEMINI_API_KEY / GEMINI_MODEL from names used by NCM PRO and LIA suites
+  when the new variables are not already defined.
+  """
+    if not os.environ.get("GEMINI_API_KEY"):
+        for key in ("LLM_API_KEY", "LLM_API_KEY_LIA"):
+            value = os.environ.get(key)
+            if value:
+                os.environ["GEMINI_API_KEY"] = value
+                break
+    if not os.environ.get("GEMINI_MODEL"):
+        value = os.environ.get("LLM_LIA_MODEL")
+        if value:
+            os.environ["GEMINI_MODEL"] = value

robotframework_gemini-0.2.0/src/robotframework_gemini/library.py

@@ -0,0 +1,221 @@
+"""Robot Framework library: Gemini oracles (text-only and optional Browser screenshots)."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+try:
+    from robot.api.deco import keyword
+except ImportError:  # pragma: no cover
+
+    def keyword(name: str | None = None, tags=()) -> Any:
+        def decorator(func):
+            return func
+
+        return decorator
+
+
+from robotframework_gemini.legacy_env import (
+    ensure_gemini_env_from_legacy,
+    ensure_importable,
+)
+from robotframework_gemini.browser_helpers import (
+    get_page_source_text,
+    take_screenshot_to_path,
+)
+from robotframework_gemini.client import GeminiOrchestrator
+
+ensure_importable()
+ensure_gemini_env_from_legacy()
+
+
+class GeminiLibrary:
+    """Keywords for Gemini text oracles and optional Browser screenshot capture."""
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str | None = None,
+    ):
+        self._api_key = api_key if api_key and str(api_key).strip() else None
+        self._model = model if model and str(model).strip() else None
+        self._orchestrator: GeminiOrchestrator | None = None
+
+    def _get_orchestrator(self) -> GeminiOrchestrator:
+        if self._orchestrator is None:
+            self._orchestrator = GeminiOrchestrator(
+                api_key=self._api_key,
+                model=self._model,
+            )
+        return self._orchestrator
+
+    # --- Generic evaluation (context + criteria) ---
+
+    @keyword("Gemini Evaluate With Image File")
+    def gemini_evaluate_with_image_file(
+        self,
+        context: str,
+        evaluation: str,
+        image_path: str,
+        extra_instructions: str | None = None,
+    ) -> str:
+        """Send context + evaluation with an existing image file (multimodal)."""
+        return self._get_orchestrator().evaluate_with_image(
+            context,
+            evaluation,
+            image_path,
+            extra_instructions=extra_instructions,
+        )
+
+    @keyword("Gemini Evaluate With Screen")
+    def gemini_evaluate_with_screen(
+        self,
+        context: str,
+        evaluation: str,
+        selector: str | None = None,
+        filename: str | None = None,
+        extra_instructions: str | None = None,
+    ) -> str:
+        """Take a Browser screenshot, then evaluate with context + criteria."""
+        path = self._resolve_screenshot_path(filename)
+        take_screenshot_to_path(path, selector=selector)
+        return self._get_orchestrator().evaluate_with_image(
+            context,
+            evaluation,
+            path,
+            extra_instructions=extra_instructions,
+        )
+
+    @keyword("Gemini Evaluate With Screen And Html")
+    def gemini_evaluate_with_screen_and_html(
+        self,
+        context: str,
+        evaluation: str,
+        include_html: bool = True,
+        filename: str | None = None,
+        extra_instructions: str | None = None,
+    ) -> str:
+        """Screenshot plus optional DOM HTML (truncated in client) for richer context."""
+        path = self._resolve_screenshot_path(filename)
+        take_screenshot_to_path(path)
+        orch = self._get_orchestrator()
+        if include_html:
+            html = get_page_source_text()
+            return orch.evaluate_with_image_and_html(
+                context,
+                evaluation,
+                path,
+                html,
+                extra_instructions=extra_instructions,
+            )
+        return orch.evaluate_with_image(
+            context,
+            evaluation,
+            path,
+            extra_instructions=extra_instructions,
+        )
+
+    @keyword("Gemini Evaluate Text")
+    def gemini_evaluate_text(
+        self,
+        context: str,
+        evaluation: str,
+        extra_instructions: str | None = None,
+    ) -> str:
+        """Text-only oracle from context + evaluation (no screenshot)."""
+        return self._get_orchestrator().evaluate_with_text(
+            context,
+            evaluation,
+            extra_instructions=extra_instructions,
+        )
+
+    @keyword("Gemini Evaluate Text Verdict")
+    def gemini_evaluate_text_verdict(
+        self,
+        context: str,
+        evaluation: str,
+        output_instructions: str,
+    ) -> str:
+        """Text judge: ``output_instructions`` defines the verdict format (e.g. Sim/Não/Aviso).
+
+        Returns raw model text. The test asserts the verdict (e.g. first line with ``Get Line``).
+        """
+        return self._get_orchestrator().evaluate_with_text(
+            context,
+            evaluation,
+            extra_instructions=output_instructions,
+        )
+
+    @keyword("Gemini Evaluate Text Rating")
+    def gemini_evaluate_text_rating(
+        self,
+        context: str,
+        evaluation: str,
+        extra_instructions: str | None = None,
+    ) -> str:
+        """Generic text judge with a 1–5 rubric (returns raw SCORE/REASON lines).
+
+        ``context`` — any test evidence (API body, logs, UI text, file excerpt, etc.).
+        ``evaluation`` — criterion to score (how well the evidence meets the test intent).
+        Use ``Gemini Parse Rating`` to extract the integer score (1–5).
+        ``extra_instructions`` is appended after the built-in rubric.
+        """
+        return self._get_orchestrator().evaluate_with_text_rating(
+            context,
+            evaluation,
+            extra_instructions=extra_instructions,
+        )
+
+    @keyword("Gemini Parse Rating")
+    def gemini_parse_rating(self, raw_response: str) -> str:
+        """Extract score 1–5 from a judge response; returns raw text if parsing fails."""
+        return GeminiOrchestrator.parse_rating(raw_response)
+
+    @keyword("Gemini Generate From Prompt")
+    def gemini_generate_from_prompt(self, prompt: str) -> str:
+        """Send a single text prompt and return the model reply (no context/evaluation template)."""
+        return self._get_orchestrator().generate_from_text(prompt)
+
+    # --- Single-prompt shortcuts (advanced) ---
+
+    @keyword("Gemini Screenshot And Ask")
+    def gemini_screenshot_and_ask(
+        self,
+        prompt: str,
+        selector: str | None = None,
+        filename: str | None = None,
+    ) -> str:
+        """
+        Take a screenshot with Browser library, send PNG + prompt to Gemini, return text.
+
+        If ``filename`` is omitted, a temp PNG under the system temp dir is used.
+        Prefer ``Gemini Evaluate With Screen`` with separate context and evaluation.
+        """
+        path = self._resolve_screenshot_path(filename)
+        take_screenshot_to_path(path, selector=selector)
+        return self._get_orchestrator().generate_with_image_file(prompt, path)
+
+    @keyword("Gemini Screenshot Html And Ask")
+    def gemini_screenshot_html_and_ask(self, prompt: str, filename: str | None = None) -> str:
+        """Screenshot full page + current page HTML (truncated inside client)."""
+        path = self._resolve_screenshot_path(filename)
+        take_screenshot_to_path(path)
+        html = get_page_source_text()
+        return self._get_orchestrator().generate_with_image_and_html(prompt, path, html)
+
+    @staticmethod
+    def _resolve_screenshot_path(filename: str | None) -> Path:
+        if filename:
+            return Path(filename)
+        fd, name = tempfile.mkstemp(prefix="robotframework-gemini-", suffix=".png")
+        os.close(fd)
+        return Path(name)
+
+
+# Backward-compatible alias for suites that import BrowserGeminiLibrary.
+BrowserGeminiLibrary = GeminiLibrary

robotframework_gemini-0.2.0/src/robotframework_gemini/prompt_build.py

@@ -0,0 +1,71 @@
+"""Compose neutral Portuguese prompts from context + evaluation criteria."""
+
+DEFAULT_RATING_OUTPUT_INSTRUCTIONS = """\
+Atribua uma nota inteira de 1 a 5 julgando o contexto fornecido apenas pelos critérios acima.
+O contexto pode ser qualquer evidência de teste (resposta de API, trecho de log, texto de UI, \
+transcrição, JSON, markdown, etc.) — não presuma formato de pergunta e resposta.
+
+Formato obrigatório da resposta (exatamente duas linhas):
+SCORE: <1|2|3|4|5>
+REASON: <uma frase curta justificando a nota>
+
+Rubrica (quão bem o contexto atende ao critério em ## O que avaliar):
+1 — Não atende: falha grave ou critério central ausente.
+2 — Atende minimamente: lacunas importantes ou incoerências relevantes.
+3 — Atende parcialmente: cumpre parte do critério, com ressalvas claras.
+4 — Atende bem: cumpre o critério com pequenas imperfeições.
+5 — Atende plenamente: cumpre o critério de forma clara e completa.
+
+Regras:
+- Use somente inteiros de 1 a 5 em SCORE (sem decimais, sem escala 0–10).
+- Não inclua texto antes da linha SCORE.
+- Baseie-se apenas nas evidências presentes no contexto; não invente fatos."""
+
+
+def merge_extra_instructions(
+    base: str,
+    extra_instructions: str | None = None,
+) -> str:
+    """Append caller overrides after structured base instructions."""
+    parts = [base.strip()]
+    if extra_instructions and extra_instructions.strip():
+        parts.append(extra_instructions.strip())
+    return "\n\n".join(parts)
+
+
+def build_evaluation_prompt(
+    context: str,
+    evaluation: str,
+    *,
+    extra_instructions: str | None = None,
+    include_visual_focus: bool = False,
+) -> str:
+    """
+    Build a single prompt from caller-supplied context and what to judge.
+
+    When ``include_visual_focus`` is True (screenshot/multimodal), remind the model
+    to rely only on what is visibly rendered.
+    """
+    parts: list[str] = []
+
+    if include_visual_focus:
+        parts.append(
+            "Uma captura de tela acompanha esta mensagem. Baseie-se apenas no que está "
+            "claramente visível na imagem (textos, números, cores e layout renderizado). "
+            "Não invente detalhes que não apareçam na captura."
+        )
+
+    parts.extend(
+        [
+            "## Contexto",
+            context.strip(),
+            "",
+            "## O que avaliar",
+            evaluation.strip(),
+        ]
+    )
+
+    if extra_instructions and extra_instructions.strip():
+        parts.extend(["", "## Instruções adicionais de resposta", extra_instructions.strip()])
+
+    return "\n".join(parts)

robotframework_gemini-0.2.0/src/robotframework_gemini/response_parse.py

@@ -0,0 +1,33 @@
+"""Normalize structured LLM outputs (e.g. 1–5 ratings) for optional test assertions."""
+
+from __future__ import annotations
+
+import re
+
+_SCORE_LINE = re.compile(
+    r"(?im)^\s*(?:score|nota)\s*:\s*([1-5])\s*$"
+)
+_SCORE_FRACTION = re.compile(r"(?i)\b([1-5])\s*/\s*5\b")
+_STANDALONE_SCORE = re.compile(r"(?m)^\s*([1-5])\s*$")
+
+
+def normalize_rating(raw: str) -> str:
+    """Extract an integer score from 1 to 5 when the model follows the rating format."""
+    text = (raw or "").strip()
+    if not text:
+        return text
+
+    match = _SCORE_LINE.search(text)
+    if match:
+        return match.group(1)
+
+    for pattern in (_SCORE_FRACTION, _STANDALONE_SCORE):
+        match = pattern.search(text)
+        if match:
+            return match.group(1)
+
+    inline = re.search(r"(?i)(?:score|nota)\s*:\s*([1-5])\b", text)
+    if inline:
+        return inline.group(1)
+
+    return text