hermex 0.1.0__tar.gz

hermex-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,151 @@
+<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/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-0.1.0/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-0.1.0/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-0.1.0/hermex/exceptions.py

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