hermex 0.1.0__py3-none-any.whl

hermex/__init__.py

@@ -0,0 +1,14 @@
+from hermex.chatgpt import ChatGPT
+from hermex.exceptions import LoginRequiredError
+from hermex.gemini import Gemini
+from hermex.models import AssistantMessage, State
+from hermex.utils import clear_data
+
+__all__ = [
+    "AssistantMessage",
+    "State",
+    "LoginRequiredError",
+    "Gemini",
+    "ChatGPT",
+    "clear_data",
+]

hermex/chatgpt.py

@@ -0,0 +1,170 @@
+from pathlib import Path
+
+import pyperclip
+from selenium.common.exceptions import NoSuchElementException, TimeoutException
+from selenium.webdriver.common.action_chains import ActionChains
+from selenium.webdriver.common.by import By
+from selenium.webdriver.common.keys import Keys
+from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.ui import WebDriverWait
+
+from hermex.config import SUPPORTED_IMAGE_EXTENSIONS
+from hermex.models import AssistantMessage, State
+from hermex.scraper_base import Scraper
+
+
+class ChatGPT(Scraper):
+    """
+    Scraper for ChatGPT (chatgpt.com).
+
+    Supports text queries, image uploads, and downloading generated images.
+    Works without login for all current features including image upload.
+    """
+
+    def open_url(self, url="https://chatgpt.com", timeout=30):
+        if "chatgpt.com" not in url:
+            raise ValueError(f"Expected a chatgpt.com URL, got: {url}")
+        super().open_url(url, timeout)
+        return self
+
+    def wait_for_page_load(self, timeout: float = 30) -> None:
+        WebDriverWait(self.driver, timeout).until(
+            EC.presence_of_element_located(
+                (By.CSS_SELECTOR, 'div[contenteditable="true"]')
+            )
+        )
+
+    def _detect_login(self):
+        try:
+            self.driver.find_element(
+                By.CSS_SELECTOR, 'button[data-testid="login-button"]'
+            )
+            self.is_logged_in = False
+        except Exception:
+            self.is_logged_in = True
+
+    def send_message(
+        self,
+        message,
+        submit=True,
+        images: list[str | Path] = None,
+        paste=False,
+        fake_typing=True,
+        typing_delay: float = None,
+    ):
+        if images:
+            self._upload_imgs(images)
+
+        wait = WebDriverWait(self.driver, 20)
+        input_box = wait.until(
+            EC.element_to_be_clickable((By.CSS_SELECTOR, 'div[contenteditable="true"]'))
+        )
+        input_box.click()
+        self.sleep(0.5)
+
+        if paste:
+            self._paste_into(
+                message, input_box, fake_typing=fake_typing, typing_delay=typing_delay
+            )
+        else:
+            self._type_into(message, input_box, typing_delay=typing_delay)
+
+        if images:
+            self._wait_until_state(State.TYPING)
+
+        if submit:
+            input_box.send_keys("\n")
+
+        return self
+
+    def _upload_imgs(self, image_paths: list[str | Path]):
+        resolved = []
+        for image_path in image_paths:
+            image_path = Path(image_path).resolve()
+            if image_path.suffix.lower() not in SUPPORTED_IMAGE_EXTENSIONS:
+                raise ValueError(
+                    f"Unsupported file type '{image_path.suffix}'. Must be one of: {SUPPORTED_IMAGE_EXTENSIONS}"
+                )
+            resolved.append(image_path)
+
+        file_input = self.driver.find_element(By.CSS_SELECTOR, "#upload-photos")
+        self.driver.execute_script("arguments[0].style.display = 'block';", file_input)
+        file_input.send_keys("\n".join(str(p) for p in resolved))
+
+    def get_last_response(
+        self, get_markdown=False, remove_watermark=False
+    ) -> AssistantMessage:
+        # ChatGPT does not watermark generated images, so remove_watermark is a no-op.
+
+        wait = WebDriverWait(self.driver, 20)
+
+        def _get_img(element: WebElement):
+            image_elems = element.find_elements(By.CSS_SELECTOR, "img")
+            if not image_elems:
+                raise NoSuchElementException("No image element in this response.")
+            self.driver.execute_script("arguments[0].click();", image_elems[0])
+            self.sleep(2)
+            down_btn = wait.until(
+                EC.presence_of_element_located(
+                    (By.CSS_SELECTOR, 'header button[aria-label="Save"]')
+                )
+            )
+            self.driver.execute_script("arguments[0].click();", down_btn)
+            img = self._get_downloaded_file()
+            self.sleep(1)
+            ActionChains(self.driver).send_keys(Keys.ESCAPE).perform()
+            self.sleep(0.5)
+            return img
+
+        def _get_text(element: WebElement, get_markdown: bool):
+            elem = element.find_element(By.CSS_SELECTOR, ".markdown")
+            inner_text = elem.text.strip()
+            if inner_text == "":
+                return None
+            if not get_markdown:
+                return inner_text
+            element.find_element(
+                By.CSS_SELECTOR, 'button[aria-label="Copy response"]'
+            ).click()
+            self.sleep(0.5)
+            return pyperclip.paste()
+
+        responses = wait.until(
+            EC.presence_of_all_elements_located((By.CSS_SELECTOR, ".agent-turn"))
+        )
+
+        if not responses:
+            raise TimeoutException("No responses found in the chat.")
+
+        last_response = responses[-1]
+
+        try:
+            text_content = _get_text(last_response, get_markdown)
+        except NoSuchElementException:
+            text_content = None
+
+        try:
+            img = _get_img(last_response)
+        except NoSuchElementException:
+            img = None
+
+        if text_content is None and img is None:
+            raise RuntimeError("Response contained neither text nor image.")
+
+        return AssistantMessage(text=text_content, image=img)
+
+    def get_state(self) -> State:
+        if self.driver.find_elements(By.CSS_SELECTOR, '[data-testid="stop-button"]'):
+            return State.GENERATING
+
+        try:
+            send_btn = self.driver.find_element(
+                By.CSS_SELECTOR, '[data-testid="send-button"]'
+            )
+        except NoSuchElementException:
+            return State.IDLE
+
+        if send_btn.get_attribute("disabled"):
+            return State.UPLOADING
+        return State.TYPING

hermex/config.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from platformdirs import user_data_dir
+
+SUPPORTED_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg"}
+data_dir = Path(user_data_dir("hermex", appauthor=False))
+LONG_WAIT = 5 * 60
+SHORT_WAIT = 7
+MIN_CHROME_VERSION = 130

hermex/exceptions.py

@@ -0,0 +1,2 @@
+class LoginRequiredError(Exception):
+    pass

hermex/gemini.py

@@ -0,0 +1,212 @@
+from pathlib import Path
+
+import pyperclip
+from selenium.common.exceptions import NoSuchElementException, TimeoutException
+from selenium.webdriver.common.by import By
+from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.ui import WebDriverWait
+
+from hermex.config import SUPPORTED_IMAGE_EXTENSIONS
+from hermex.exceptions import LoginRequiredError
+from hermex.gemini_watermark_remover import gemini_remove_watermark
+from hermex.models import AssistantMessage, State
+from hermex.scraper_base import Scraper
+
+
+class Gemini(Scraper):
+    """
+    Scraper for Google Gemini (gemini.google.com).
+
+    Supports text queries, image uploads, and downloading generated images.
+    Works in guest mode for basic text queries; image upload requires a
+    logged-in session established via `Gemini.setup()`.
+
+    Generated images are optionally post-processed to remove the Gemini
+    watermark via `remove_watermark=True` on `query()` or `get_last_response()`.
+    """
+
+    def open_url(self, url="https://gemini.google.com", timeout=30):
+        if "gemini.google.com" not in url:
+            raise ValueError(f"Expected a gemini.google.com URL, got: {url}")
+        super().open_url(url, timeout)
+        return self
+
+    def wait_for_page_load(self, timeout: float = 30) -> None:
+        WebDriverWait(self.driver, timeout).until(
+            EC.presence_of_element_located((By.TAG_NAME, "rich-textarea"))
+        )
+
+    def _detect_login(self):
+        try:
+            WebDriverWait(self.driver, 3).until(
+                EC.presence_of_element_located(
+                    (By.CSS_SELECTOR, 'a[aria-label="Sign in"]')
+                )
+            )
+            self.is_logged_in = False
+        except TimeoutException:
+            self.is_logged_in = True
+
+    def send_message(
+        self,
+        message: str,
+        submit=True,
+        images: list[str | Path] = None,
+        paste=False,
+        fake_typing=True,
+        typing_delay: float = None,
+    ):
+        wait = WebDriverWait(self.driver, 20)
+        input_box = wait.until(
+            EC.element_to_be_clickable((By.TAG_NAME, "rich-textarea"))
+        )
+
+        if images:
+            if not self.is_logged_in:
+                raise LoginRequiredError(
+                    "Image upload requires login. Run Gemini.setup() to log in."
+                )
+            self._upload_imgs(images)
+
+        input_box.click()
+        self.sleep(0.5)
+        input_p = input_box.find_element(By.TAG_NAME, "p")
+
+        if paste:
+            self._paste_into(
+                message, input_p, fake_typing=fake_typing, typing_delay=typing_delay
+            )
+        else:
+            self._type_into(message, input_p, typing_delay=typing_delay)
+
+        if images:
+            self._wait_until_state(State.TYPING)
+
+        if submit:
+            input_p.send_keys("\n")
+
+        return self
+
+    def _upload_imgs(self, image_paths: list[str | Path]):
+        resolved = []
+        for image_path in image_paths:
+            image_path = Path(image_path).resolve()
+            if image_path.suffix.lower() not in SUPPORTED_IMAGE_EXTENSIONS:
+                raise ValueError(
+                    f"Unsupported file type '{image_path.suffix}'. Must be one of: {SUPPORTED_IMAGE_EXTENSIONS}"
+                )
+            resolved.append(image_path)
+
+        wait = WebDriverWait(self.driver, 10)
+
+        # Gemini's JS calls input.click() internally when the upload menu item is clicked,
+        # which would open an OS file dialog we can't control. Patch the prototype before
+        # any clicks so that call is silently suppressed. The patch is restored after upload.
+        self.driver.execute_script("""
+            const orig = HTMLInputElement.prototype.click;
+            HTMLInputElement.prototype.click = function() {
+                if (this.type === 'file') return;
+                return orig.apply(this, arguments);
+            };
+            window.__restoreFileClick = () => { HTMLInputElement.prototype.click = orig; };
+        """)
+
+        self.driver.find_element(
+            By.CSS_SELECTOR,
+            '[data-node-type="input-area"] button[aria-label="Open upload file menu"]',
+        ).click()
+
+        # Clicking "Upload files" creates the hidden input[name="Filedata"] and triggers .click() on it.
+        wait.until(
+            EC.element_to_be_clickable(
+                (By.CSS_SELECTOR, '[data-test-id="local-images-files-uploader-button"]')
+            )
+        ).click()
+
+        # The input is display:none — unhide it so Selenium accepts send_keys.
+        # send_keys on a file input bypasses the OS dialog entirely (ChromeDriver handles it internally).
+        file_input = wait.until(
+            EC.presence_of_element_located((By.CSS_SELECTOR, 'input[name="Filedata"]'))
+        )
+        self.driver.execute_script("arguments[0].style.display = 'block';", file_input)
+        file_input.send_keys("\n".join(str(p) for p in resolved))
+        self.driver.execute_script(
+            "window.__restoreFileClick && window.__restoreFileClick();"
+        )
+
+    def get_last_response(
+        self, get_markdown=False, remove_watermark=False
+    ) -> AssistantMessage:
+        def _get_img(element: WebElement):
+            element.find_element(
+                By.TAG_NAME, "download-generated-image-button"
+            ).find_element(By.TAG_NAME, "button").click()
+            img = self._get_downloaded_file()
+            return img
+
+        def _get_text(element: WebElement, get_markdown):
+            elem = element.find_element(By.CSS_SELECTOR, ".markdown")
+            inner_text = elem.text.strip()
+            if inner_text == "":
+                return None
+            if not get_markdown:
+                return inner_text
+            element.find_element(By.TAG_NAME, "copy-button").click()
+            self.sleep(0.5)
+            return pyperclip.paste()
+
+        wait = WebDriverWait(self.driver, 20)
+        responses = wait.until(
+            EC.presence_of_all_elements_located((By.TAG_NAME, "model-response"))
+        )
+        last_response = responses[-1]
+
+        try:
+            text_content = _get_text(last_response, get_markdown)
+        except NoSuchElementException:
+            text_content = None
+
+        try:
+            img = _get_img(last_response)
+        except NoSuchElementException:
+            img = None
+
+        if text_content is None and img is None:
+            raise RuntimeError("Response contained neither text nor image.")
+
+        if remove_watermark and img is not None:
+            gemini_remove_watermark(str(img), str(img))
+
+        return AssistantMessage(text=text_content, image=img)
+
+    def get_state(self) -> State:
+        input_area = self.driver.find_element(
+            By.CSS_SELECTOR, '[data-node-type="input-area"]'
+        )
+
+        send_stop = input_area.find_element(
+            By.CSS_SELECTOR, '[aria-label="Send message"], [aria-label="Stop response"]'
+        )
+        # While generating, Gemini swaps the send button's aria-label to "Stop response".
+        if send_stop.get_attribute("aria-label") == "Stop response":
+            return State.GENERATING
+
+        # During upload, the send button is disabled (aria-disabled="true") but still
+        # focusable (tabindex="0"). In IDLE the button is also disabled but tabindex="-1",
+        # so tabindex is the only signal that distinguishes the two states.
+        if (
+            send_stop.get_attribute("aria-disabled") == "true"
+            and send_stop.get_attribute("tabindex") == "0"
+        ):
+            return State.UPLOADING
+
+        # When the input has content, Gemini hides the mic button to reveal the send button.
+        mic = input_area.find_element(By.CSS_SELECTOR, '[aria-label="Microphone"]')
+        container = mic.find_element(
+            By.XPATH, 'ancestor::*[contains(@class, "mic-button-container")]'
+        )
+        if "hidden" in container.get_attribute("class"):
+            return State.TYPING
+
+        return State.IDLE

hermex/gemini_watermark_remover.py

@@ -0,0 +1,70 @@
+from importlib.resources import files
+
+import cv2
+import numpy as np
+
+_ASSETS_DIR = files("hermex") / "assets"
+
+_alpha_map_small = None
+_alpha_map_large = None
+
+
+def _calc_alpha(img, size):
+    if img.shape[:2] != size:
+        img = cv2.resize(img, size, interpolation=cv2.INTER_AREA)
+    return np.max(img, axis=2).astype(np.float32) / 255.0
+
+
+def _load_assets():
+    global _alpha_map_small, _alpha_map_large
+    if _alpha_map_small is not None:
+        return
+
+    bg_small = cv2.imread(str(_ASSETS_DIR / "bg_48.png"))
+    bg_large = cv2.imread(str(_ASSETS_DIR / "bg_96.png"))
+    if bg_small is None or bg_large is None:
+        raise ValueError(
+            f"Could not load watermark reference assets from {_ASSETS_DIR}."
+        )
+    _alpha_map_small = _calc_alpha(bg_small, (48, 48))
+    _alpha_map_large = _calc_alpha(bg_large, (96, 96))
+
+
+def _get_config(width, height):
+    if width > 1024 and height > 1024:
+        return {"margin": 64, "size": 96, "map": _alpha_map_large}
+    else:
+        return {"margin": 32, "size": 48, "map": _alpha_map_small}
+
+
+def gemini_remove_watermark(input_path: str, output_path: str):
+    _load_assets()
+
+    img = cv2.imread(input_path)
+    if img is None:
+        raise ValueError(f"Could not read input image: {input_path}")
+
+    h, w = img.shape[:2]
+    config = _get_config(w, h)
+    alpha_map = config["map"]
+    size = config["size"]
+    margin = config["margin"]
+
+    x = w - margin - size
+    y = h - margin - size
+
+    if x < 0 or y < 0:
+        raise ValueError(f"Image too small to process: {input_path}")
+
+    roi = img[y : y + size, x : x + size].astype(np.float32)
+
+    alpha = alpha_map[:, :, np.newaxis]
+    alpha_clamped = np.minimum(alpha, 0.99)
+    restored_roi = (roi - (alpha * 255.0)) / (1.0 - alpha_clamped)
+    restored_roi = np.clip(restored_roi, 0, 255)
+
+    mask_3ch = np.repeat(alpha > 0.002, 3, axis=2)
+    final_roi = np.where(mask_3ch, restored_roi, roi)
+
+    img[y : y + size, x : x + size] = final_roi.astype(np.uint8)
+    cv2.imwrite(output_path, img)

hermex/models.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class State(str, Enum):
+    """Current UI state of the chatbot interface."""
+
+    IDLE = "idle"
+    """Ready and waiting for input."""
+
+    GENERATING = "generating"
+    """Model is actively producing a response."""
+
+    TYPING = "typing"
+    """Input box has content that has not been submitted yet."""
+
+    UPLOADING = "uploading"
+    """A file upload is in progress."""
+
+
+@dataclass
+class AssistantMessage:
+    """Result returned by `query()` and `get_last_response()`."""
+
+    text: str | None = None
+    """Plain text content of the response, or markdown if `get_markdown=True`. None if the response is image-only."""
+
+    image: Path | None = None
+    """Path to the downloaded image file. None if the response contains no image."""

hermex/scraper_base.py

@@ -0,0 +1,450 @@
+import random
+import re
+import subprocess
+import time
+import warnings
+from abc import ABC, abstractmethod
+from pathlib import Path
+from shutil import move as move_file
+from tempfile import TemporaryDirectory
+
+import undetected_chromedriver as uc
+from selenium.common.exceptions import TimeoutException
+from selenium.webdriver.common.keys import Keys
+from selenium.webdriver.remote.webelement import WebElement
+
+from hermex.config import LONG_WAIT, MIN_CHROME_VERSION, SHORT_WAIT
+from hermex.config import data_dir as _default_data_dir
+from hermex.models import AssistantMessage, State
+from hermex.utils import get_user_agent
+
+
+def _detect_chrome_version() -> int:
+    chrome = uc.find_chrome_executable()
+    out = subprocess.check_output([chrome, "--version"], text=True)
+    version = int(re.search(r"(\d+)\.", out).group(1))
+    if version < MIN_CHROME_VERSION:
+        raise RuntimeError(
+            f"Chrome {version} is not supported. Hermex requires Chrome {MIN_CHROME_VERSION} or higher."
+        )
+    return version
+
+
+class Scraper(ABC):
+    """
+    Abstract base class for LLM chatbot scrapers.
+
+    Manages the Chrome browser lifecycle, simulated typing, file downloads,
+    and state polling. Subclasses implement the platform-specific DOM interactions
+    for a particular chatbot (e.g. Gemini, ChatGPT).
+
+    Use `Scraper.setup()` once to establish a persistent login session, then
+    instantiate the subclass directly for subsequent runs.
+    """
+
+    _state_error_tolerance = (
+        20  # seconds of consecutive state-detection failures before giving up
+    )
+
+    def __init__(
+        self,
+        chrome_version=None,
+        download_dir=Path("."),
+        headless=False,
+        typing_delay=0.025,
+        disable_web_security=True,
+        data_dir=None,
+    ):
+        """
+        :param chrome_version: Chrome major version number. Defaults to auto-detecting
+            the installed Chrome version.
+        :param download_dir: Directory where downloaded files (e.g. generated images)
+            are saved.
+        :param headless: Run the browser without a visible window.
+        :param typing_delay: Seconds between each keystroke when typing
+            character-by-character.
+        :param disable_web_security: Pass --disable-web-security to Chrome. Needed for
+            some scrapers (e.g. ChatGPT, Gemini) but triggers bot detection on stricter
+            sites — set False for those.
+        :param data_dir: Root directory where Hermex stores its data. Defaults to the
+            platform-appropriate data directory (~/.local/share/hermex on Linux,
+            ~/Library/Application Support/hermex on macOS). Browser profiles are stored
+            as subdirectories within this path (e.g. data_dir/chrome_profile/).
+        """
+        if data_dir is None:
+            data_dir = _default_data_dir
+        self._data_dir = Path(data_dir)
+        self.browser_profile_dir = self._data_dir / "chrome_profile"
+        self.chrome_version = chrome_version or _detect_chrome_version()
+        self.disable_web_security = disable_web_security
+        self._temp_dir = TemporaryDirectory()
+        self._selenium_download_dir = Path(self._temp_dir.name)
+        self.download_dir = Path(download_dir)
+        self.headless = headless
+        self.driver = None
+        self.typing_delay = typing_delay
+        self.is_logged_in = False
+
+        self.download_dir.mkdir(parents=True, exist_ok=True)
+
+        if not (self._data_dir / f".setup_{self.__class__.__name__.lower()}").exists():
+            warnings.warn(
+                f"{self.__class__.__name__}.setup() has not been run. "
+                "It is strongly recommended to run it once before use — it builds a "
+                "browser profile that significantly reduces bot detection risk.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+    def _initialize_driver(self):
+        """Initialize and configure the Chrome driver"""
+        options = uc.ChromeOptions()
+        options.add_argument("--start-maximized")
+        options.add_argument("--disable-notifications")
+        options.add_argument(f"--user-data-dir={self.browser_profile_dir}")
+        options.add_argument("--enable-javascript")
+        options.add_argument("--enable-cookies")
+        options.add_argument("--no-sandbox")
+        if self.disable_web_security:
+            options.add_argument("--disable-web-security")
+            options.add_argument("--allow-running-insecure-content")
+        options.add_argument("--disable-blink-features=AutomationControlled")
+        options.add_argument("--disable-features=IsolateOrigins,site-per-process")
+
+        options.add_argument(f"--user-agent={get_user_agent(self.chrome_version)}")
+
+        options.add_experimental_option(
+            "prefs",
+            {
+                "download.default_directory": str(self._selenium_download_dir),
+                "download.prompt_for_download": False,
+                "download.directory_upgrade": True,
+                "safebrowsing.enabled": False,
+            },
+        )
+
+        if self.headless:
+            options.add_argument("--headless")
+            options.add_argument("--disable-gpu")
+            options.add_argument("--window-size=1920,1080")
+
+        self.driver = uc.Chrome(
+            options=options, use_subprocess=True, version_main=self.chrome_version
+        )
+        return self
+
+    def open_url(self, url=None, timeout=30):
+        """
+        Open a URL in the browser and wait for the page to be ready.
+
+        :param url: URL to navigate to.
+        :param timeout: Maximum seconds to wait for the page to be ready before raising
+            TimeoutException.
+        """
+        if not self.driver:
+            self._initialize_driver()
+
+        self.driver.get(url)
+        self.wait_for_page_load(timeout)
+        self._detect_login()
+
+        return self
+
+    @abstractmethod
+    def wait_for_page_load(self, timeout: float = 30) -> None:
+        """Wait until the page is ready to interact with."""
+
+    @abstractmethod
+    def _detect_login(self) -> None:
+        """Detect whether the user is logged in and set self.is_logged_in accordingly."""
+
+    @abstractmethod
+    def send_message(
+        self,
+        message: str,
+        submit: bool = True,
+        images: list[str | Path] = None,
+        paste: bool = False,
+        fake_typing: bool = True,
+        typing_delay: float = None,
+    ) -> "Scraper":
+        """
+        Input a message into the chat, optionally attaching images.
+
+        :param message: Text to send.
+        :param submit: Whether to press Enter after composing the message.
+        :param images: List of image file paths to attach before the message.
+        :param paste: If True, paste the message instead of typing it character by
+                      character. Useful for long messages where typing is too slow.
+        :param fake_typing: When paste=True, type dummy text first to avoid bot
+                            detection, then replace it with the real message.
+        :param typing_delay: Seconds between each keystroke. Overrides the
+                             instance-level default set in the constructor for this call
+                             only.
+        """
+
+    @abstractmethod
+    def get_last_response(
+        self, get_markdown: bool = False, remove_watermark: bool = False
+    ) -> "AssistantMessage":
+        """
+        Retrieve the last response from the chat interface.
+
+        :param get_markdown: If True, return the raw markdown source instead of plain text.
+        :param remove_watermark: If True, remove the watermark from any downloaded image.
+        :return: AssistantMessage with text and image fields (either may be None, but not both).
+        """
+
+    @abstractmethod
+    def get_state(self) -> State:
+        """
+        Return the current state of the chatbot UI.
+
+        Possible states:
+        - State.IDLE: the interface is ready and waiting for input.
+        - State.TYPING: the input box has content that has not been submitted yet.
+        - State.UPLOADING: a file upload is in progress.
+        - State.GENERATING: the model is actively generating a response.
+
+        :return: A State value representing the current UI state.
+        :raises Exception: if the state cannot be determined (e.g. expected DOM elements
+            are missing). Callers that need to tolerate transient failures should use
+            wait_until_idle() instead, which has built-in error tolerance.
+        """
+
+    def _wait_until_state(self, target: State, timeout: float = None) -> None:
+        if timeout is None:
+            timeout = LONG_WAIT
+        start = time.time()
+        error_since = None
+        while time.time() - start < timeout:
+            try:
+                if self.get_state() == target:
+                    return
+                error_since = None
+            except Exception:
+                if error_since is None:
+                    error_since = time.time()
+                elif time.time() - error_since > self._state_error_tolerance:
+                    raise
+            time.sleep(1)
+        raise TimeoutException(
+            f"Chatbot did not reach state '{target}' within {timeout}s."
+        )
+
+    def wait_until_idle(self, timeout: float = None) -> None:
+        """
+        Block until the chatbot has finished generating its response.
+
+        :param timeout: Maximum seconds to wait before raising TimeoutException. Defaults to 5 minutes.
+        """
+        self._wait_until_state(State.IDLE, timeout)
+
+    def query(
+        self,
+        message: str,
+        timeout: float = None,
+        images: list[str | Path] = None,
+        paste: bool = False,
+        fake_typing: bool = True,
+        typing_delay: float = None,
+        get_markdown: bool = False,
+        remove_watermark: bool = False,
+    ) -> "AssistantMessage":
+        """
+        Send a message, wait for the response to complete, and return it.
+
+        :param message: Text to send.
+        :param timeout: Maximum seconds to wait for the response before raising TimeoutException. Defaults to 5 minutes.
+        :param images: List of image file paths to attach (platform-dependent).
+        :param paste: If True, paste the message instead of typing it character by character.
+                      Useful for long messages where typing is too slow.
+        :param fake_typing: When paste=True, type dummy text first to avoid bot detection,
+                            then replace it with the real message.
+        :param typing_delay: Seconds between each keystroke. Overrides the instance-level default.
+        :param get_markdown: If True, return the raw markdown source instead of plain text.
+        :param remove_watermark: If True, remove the watermark from any downloaded image.
+        :return: AssistantMessage with text and image fields (either may be None, but not both).
+        """
+        self.send_message(
+            message,
+            images=images,
+            paste=paste,
+            fake_typing=fake_typing,
+            typing_delay=typing_delay,
+        )
+        self.wait_until_idle(timeout)
+        return self.get_last_response(
+            get_markdown=get_markdown, remove_watermark=remove_watermark
+        )
+
+    def _type_into(
+        self,
+        message: str,
+        input_box: WebElement,
+        typing_delay: float = None,
+    ):
+        delay = typing_delay if typing_delay is not None else self.typing_delay
+        for char in message:
+            if char == "\n":  # Handle Newline: Shift+Enter
+                input_box.send_keys(Keys.SHIFT, Keys.ENTER)
+            elif ord(char) > 0xFFFF:  # Handle Emojies
+                self.driver.execute_script(
+                    "document.execCommand('insertText', false, arguments[0]);", char
+                )
+            else:
+                input_box.send_keys(char)
+            self.sleep(delay)
+
+        self.sleep(2)
+        return self
+
+    def _paste_into(
+        self,
+        message: str,
+        input_box: WebElement,
+        fake_typing=True,
+        typing_delay: float = None,
+    ):
+        if fake_typing:
+            self._type_into(
+                "Some fake text... " * 20, input_box, typing_delay=typing_delay
+            )
+            self.driver.execute_script(
+                "document.execCommand('selectAll', false, null);"
+            )
+
+        self.driver.execute_script(
+            "document.execCommand('insertText', false, arguments[0]);", message
+        )
+        self.sleep(2)
+        return self
+
+    def sleep(self, t):
+        """
+        Sleep for approximately t seconds, with a small random jitter to appear more human-like.
+
+        :param t: Target sleep duration in seconds.
+        """
+        minmax_factor = 0.2
+        min_time = t - t * minmax_factor
+        max_time = t + t * minmax_factor
+        time.sleep(random.uniform(min_time, max_time))
+
+        return self
+
+    def long_wait(self):
+        """Wait for the default long duration (5 minutes). Use after sending a prompt
+        that triggers image generation or a slow response."""
+        return self.sleep(LONG_WAIT)
+
+    def short_wait(self):
+        """Wait for the default short duration (7 seconds). Use after UI interactions
+        that need a moment to settle."""
+        return self.sleep(SHORT_WAIT)
+
+    def refresh_page(self):
+        """Reload the current page."""
+        self.driver.refresh()
+        return self
+
+    def get_current_url(self, only_base=False):
+        """
+        Return the current browser URL.
+
+        :param only_base: If True, strip query parameters and return only the base URL.
+        """
+        url = self.driver.current_url
+        if only_base:
+            return url.split("?")[0]
+        return url
+
+    def _get_downloaded_file(self, wait_time=60):
+        """Wait for a file to be downloaded and return its path"""
+        elapsed = 0
+        poll_interval = 1
+
+        while elapsed < wait_time:
+            files = list(self._selenium_download_dir.iterdir())
+            if files:
+                file = files[0]
+                dest = self.download_dir / file.name
+                move_file(file, dest)
+                return dest
+
+            time.sleep(poll_interval)
+            elapsed += poll_interval
+
+        raise TimeoutException("File download timed out.")
+
+    def close(self):
+        """Close the browser and clean up"""
+        if self.driver:
+            self.driver.quit()
+            self.driver = None
+
+    @classmethod
+    def setup(cls, data_dir=None):
+        """
+        First-time setup required before using Hermex.
+
+        Opens a browser window so you can browse around briefly. This builds a
+        browser profile that looks like a real user, which significantly reduces
+        bot detection risk in subsequent automated runs. Everyone must run this
+        at least once after installation.
+
+        If you need login-gated features (e.g. image upload), log in
+        during this session. Hermex will reuse the saved session in all future
+        runs — repeat setup only if your session expires.
+
+        Close the browser window when done.
+
+        :param data_dir: Must match the data_dir you pass to the constructor. Defaults
+            to the platform-appropriate data directory.
+
+        Usage:
+            Gemini.setup()
+        """
+        if data_dir is None:
+            data_dir = _default_data_dir
+        print(
+            "==> Opening browser. Browse around briefly, then close the window when done."
+        )
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", UserWarning)
+            scraper = cls(data_dir=data_dir)
+        scraper.open_url()
+        while True:
+            try:
+                scraper.driver.window_handles
+                time.sleep(2)
+            except Exception:
+                break
+        scraper.close()
+
+        marker = Path(data_dir) / f".setup_{cls.__name__.lower()}"
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.touch()
+
+    @classmethod
+    def simple_query(cls, prompt, images=None, timeout=None):
+        """
+        Open the browser, send a prompt, and return the response.
+
+        Convenience method for one-shot scripts that don't need a persistent
+        session. Opens the browser, sends the prompt, closes the browser, and
+        returns the full AssistantMessage.
+
+        :param prompt: The prompt text to send.
+        :param images: Optional list of image file paths to attach.
+        :param timeout: Maximum seconds to wait for the response. Defaults to 5 minutes.
+        :return: AssistantMessage with text and image fields.
+        """
+        scraper = cls()
+        response = (
+            scraper.open_url()
+            .short_wait()
+            .query(prompt, images=images, timeout=timeout)
+        )
+        scraper.close()
+        return response

hermex/utils.py

@@ -0,0 +1,43 @@
+import shutil
+import sys
+from pathlib import Path
+
+from hermex.config import data_dir as _default_data_dir
+
+
+def get_user_agent(chrome_version: int) -> str:
+    version_str = f"{chrome_version}.0.0.0"
+    if sys.platform == "darwin":
+        return (
+            f"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+            f"AppleWebKit/537.36 (KHTML, like Gecko) "
+            f"Chrome/{version_str} Safari/537.36"
+        )
+    elif sys.platform == "win32":
+        return (
+            f"Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+            f"AppleWebKit/537.36 (KHTML, like Gecko) "
+            f"Chrome/{version_str} Safari/537.36"
+        )
+    elif sys.platform.startswith("linux"):
+        return (
+            f"Mozilla/5.0 (X11; Linux x86_64) "
+            f"AppleWebKit/537.36 (KHTML, like Gecko) "
+            f"Chrome/{version_str} Safari/537.36"
+        )
+    else:
+        raise NotImplementedError(
+            f"User agent not defined for platform: {sys.platform}"
+        )
+
+
+def clear_data(data_dir=_default_data_dir):
+    """
+    Delete all data stored by Hermex (browser profiles, etc.).
+
+    :param data_dir: Root data directory to remove. Defaults to the platform-appropriate
+        Hermex data directory. Pass a custom path if you initialised scrapers with one.
+    """
+    data_dir = Path(data_dir).expanduser()
+    if data_dir.exists():
+        shutil.rmtree(data_dir)

hermex-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: hermex
+Version: 0.1.0
+Summary: Drive ChatGPT and Gemini from Python — no API keys, no billing, just the free web UI.
+Author-email: Usama <pseudo.usama@gmail.com>
+License: MIT
+Project-URL: Homepage, https://hermex.usama.ai
+Project-URL: Documentation, https://hermex.usama.ai
+Project-URL: Repository, https://github.com/pseudo-usama/hermex
+Keywords: chatgpt,gemini,llm,scraper,automation,selenium,browser
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: selenium>=4.0
+Requires-Dist: undetected-chromedriver>=3.5
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: opencv-python>=4.0
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mkdocstrings[python]; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pseudo-usama/hermex/main/docs/assets/logo.svg" alt="Hermex" width="450" style="margin: 24px 0;"/>
+  <br>
+  <em>Drive ChatGPT and Gemini from Python — no API keys, no billing, just the free web UI.</em>
+  <br><br>
+  <a href="https://pypi.org/project/hermex"><img src="https://img.shields.io/pypi/v/hermex?color=3cb371" alt="PyPI"/></a>
+  <img src="https://img.shields.io/pypi/pyversions/hermex?color=3cb371" alt="Python 3.11+"/>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"/>
+  <a href="https://github.com/pseudo-usama/hermex"><img src="https://img.shields.io/badge/GitHub-Hermex-181717?logo=github" alt="GitHub Repo"/></a>
+</p>
+
+---
+
+ChatGPT and Gemini are incredibly capable — but their official APIs are expensive, and for many tasks you simply don't need them. If you want to run OCR on an image, generate artwork, extract text from a screenshot, or just ask a quick question in a script, paying per-token for API access is overkill when the free web UI can do the same thing.
+
+Hermex lets you drive ChatGPT and Gemini from Python just like a human would: it opens a real Chrome browser, types your message, uploads your images, waits for the response, and hands it back to you as a Python object. No API keys, no billing, no rate-limit tiers.
+
+```python
+from hermex import ChatGPT
+
+response = ChatGPT.simple_query("What does this receipt say?", images=["receipt.jpg"])
+print(response.text)
+```
+
+It uses undetected-chromedriver under the hood to avoid bot detection, and reuses a persistent browser profile so your login session survives across runs.
+
+## Installation
+
+```bash
+pip install hermex
+```
+
+Requires Python 3.11+ and Google Chrome 130+.
+
+## First-time setup
+
+Hermex reuses a persistent Chrome profile so you only need to log in once:
+
+```python
+from hermex import Gemini
+
+Gemini.setup()  # opens a browser — log in, browse briefly, then close the window
+```
+
+After setup, all future runs reuse the saved session automatically. Repeat this if your session expires.
+
+Guest mode (no login) works for basic text queries on Gemini but image upload requires a logged-in session. ChatGPT works without login for all features including image upload.
+
+## Usage
+
+### Single query
+
+```python
+from hermex import Gemini, ChatGPT
+
+# Gemini
+gemini = Gemini()
+gemini.open_url()
+response = gemini.query("Summarize the history of the internet.")
+print(response.text)
+gemini.close()
+
+# ChatGPT
+chatgpt = ChatGPT()
+chatgpt.open_url()
+response = chatgpt.query("Summarize the history of the internet.")
+print(response.text)
+chatgpt.close()
+```
+
+### Sending images
+
+```python
+response = gemini.query(
+    "Describe what's in this image.",
+    images=["photo.jpg"],
+)
+print(response.text)
+```
+
+### One-shot query
+
+```python
+from hermex import Gemini, ChatGPT
+
+response = Gemini.simple_query("What is the capital of France?")
+print(response.text)
+
+response = ChatGPT.simple_query("What is the capital of France?")
+print(response.text)
+
+# With an image
+response = Gemini.simple_query("Describe this image.", images=["photo.jpg"])
+print(response.text)
+```
+
+## AssistantMessage object
+
+`query()` and `get_last_response()` return an `AssistantMessage` dataclass:
+
+```python
+@dataclass
+class AssistantMessage:
+    text: str | None   # plain text (or markdown if get_markdown=True)
+    image: Path | None # path to downloaded image, or None
+```
+
+## API reference
+
+Both `Gemini` and `ChatGPT` share the same interface — all methods below apply to both unless noted.
+
+| Method | Description |
+|---|---|
+| `open_url(url, timeout)` | Open the chat interface in the browser |
+| `send_message(message, submit, images, paste, fake_typing, typing_delay)` | Type and optionally submit a message |
+| `query(message, timeout, images, paste, get_markdown, remove_watermark)` | Send a message, wait for the response, and return it |
+| `get_last_response(get_markdown, remove_watermark)` | Retrieve the most recent response |
+| `wait_until_idle(timeout)` | Block until the chatbot finishes generating |
+| `get_state()` | Return the current UI state (`State.IDLE`, `GENERATING`, `TYPING`, `UPLOADING`) |
+| `simple_query(prompt, images, timeout)` | Class method — open, query, close in one call |
+| `short_wait()` | Sleep ~7 seconds |
+| `long_wait()` | Sleep ~5 minutes |
+| `refresh_page()` | Reload the current page |
+| `close()` | Close the browser |
+| `setup()` | One-time login setup (class method) |
+
+### Constructor options
+
+```python
+Gemini(
+    chrome_version=None,      # auto-detected from installed Chrome
+    download_dir=Path("."),   # where generated images are saved
+    headless=False,
+    typing_delay=0.025,       # seconds between keystrokes
+    disable_web_security=True,
+)
+# ChatGPT accepts the same parameters
+```
+
+## Watermark removal
+
+Gemini watermarks its generated images. Pass `remove_watermark=True` to strip it:
+
+```python
+response = gemini.query("Generate an image of a sunset.", remove_watermark=True)
+```
+
+## Notes
+
+- Bot detection is mitigated through per-character typing delays, fake typing before paste, a persistent browser profile, and a spoofed user agent. Avoid running headless for sensitive sessions.
+- Browser profile and session data are stored in the platform data directory (`~/Library/Application Support/hermex` on macOS).

hermex-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+hermex/__init__.py,sha256=EVvI4p48rvJ4JFd-WiuLy12x-CnbBXrm2pR7r1cWQdc,328
+hermex/chatgpt.py,sha256=VBkn4BnGdTDBAQ2nahgUQd6J37aWZnr9M2QtXMaG8aY,5884
+hermex/config.py,sha256=sIg9zLyp2jL3sU19i_nvTuo78ORCB6bZQ13RzcjbTfk,238
+hermex/exceptions.py,sha256=BzVSEhe6koXcqAFlR1WFumYS5nzAK40SeURhScybYkk,46
+hermex/gemini.py,sha256=AuTYYoLATPIhrsSWZLSsb9mGgAx9DIbLBoK7RKqGhvo,8092
+hermex/gemini_watermark_remover.py,sha256=0Fgzl8Y79AZ2lfNWehdN_8qKjN69rhWcUffODQSbckA,2034
+hermex/models.py,sha256=Gd2JGpxf-jKke_UMsSIV86mLT8kCXlJEmgs1K6oRvP4,822
+hermex/scraper_base.py,sha256=m0J_E515CjxIM1mm5jYwmFzERm55qVG2zdXe9v1bOY4,16936
+hermex/utils.py,sha256=Ijf902yuk6h3zc5_f710Ka615HdRMjb__6igX7vyZLQ,1403
+hermex/assets/bg_48.png,sha256=0vxfyPpe6kmuKURDb2d4nZR0btv7BtYMbfkYuZ_8utQ,1985
+hermex/assets/bg_96.png,sha256=Xy9kzsxRSvysH1USgof3BdNLQnaerEwFEzbZl-B90vk,9044
+hermex-0.1.0.dist-info/licenses/LICENSE,sha256=D38kxrHy69-dEG1UgREItynBc4BRoqQAJcUWzXj0FdQ,1356
+hermex-0.1.0.dist-info/METADATA,sha256=b8ZN8AQXlcw0cTFQoFQD1R9gdoGKGbJxIrCKiISK9kQ,6668
+hermex-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hermex-0.1.0.dist-info/top_level.txt,sha256=i-5LsdJ954ahrPbto1XJ5iC0R9jC6-txPyINoSkoqPI,7
+hermex-0.1.0.dist-info/RECORD,,

hermex-0.1.0.dist-info/WHEEL

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

hermex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Usama (PSEUDO)
+
+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.
+
+---
+
+The watermark removal logic in hermex/gemini_watermark_remover.py is adapted
+from GeminiWatermarkTool (https://github.com/allenk/GeminiWatermarkTool) by
+allenk, originally written in C++ and rewritten in Python for this project.
+That work is also released under the MIT License.

hermex-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hermex