gemx 0.1.0__py3-none-any.whl

gemx/__init__.py

@@ -0,0 +1,29 @@
+"""Gemx — drive the Gemini web UI from Python.
+
+A play on "Gemini". Treats ``gemini.google.com`` as if it were an API.
+"""
+
+from __future__ import annotations
+
+from .client import Gemx, GemxConfig
+from .errors import (
+    GemxError,
+    InputError,
+    ResponseParseError,
+    ResponseTimeoutError,
+)
+from .formats import OutputFormat, format_instruction, parse_output
+
+__all__ = [
+    "Gemx",
+    "GemxConfig",
+    "GemxError",
+    "InputError",
+    "OutputFormat",
+    "ResponseParseError",
+    "ResponseTimeoutError",
+    "format_instruction",
+    "parse_output",
+]
+
+__version__ = "0.1.0"

gemx/cli.py

@@ -0,0 +1,114 @@
+"""Command-line interface: ``gemx``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+from pathlib import Path
+from xml.etree import ElementTree as ET
+
+from . import __version__
+from .client import Gemx, GemxConfig
+from .errors import GemxError
+from .formats import OutputFormat
+
+DEFAULT_PROFILE_DIR = Path("~/.gemx/profile")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the ``gemx`` argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="gemx",
+        description="Drive the Gemini web UI from the command line.",
+    )
+    parser.add_argument("--version", action="version", version=f"gemx {__version__}")
+    parser.add_argument(
+        "prompt",
+        nargs="?",
+        help="Prompt to send. If omitted, read from stdin.",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        type=OutputFormat.from_str,
+        default=OutputFormat.JSON,
+        metavar="{json,xml,txt}",
+        help="Output format requested from Gemini (default: json).",
+    )
+    parser.add_argument(
+        "-p",
+        "--profile-dir",
+        type=Path,
+        default=DEFAULT_PROFILE_DIR,
+        help=f"Chrome profile dir for the session (default: {DEFAULT_PROFILE_DIR}).",
+    )
+    parser.add_argument(
+        "--headful",
+        action="store_true",
+        help="Show the browser window instead of running headless.",
+    )
+    parser.add_argument(
+        "--response-timeout",
+        type=int,
+        default=180,
+        metavar="SECONDS",
+        help="Max seconds to wait for a response to start (default: 180).",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Log progress to stderr.",
+    )
+    return parser
+
+
+def _render(value: object, fmt: OutputFormat) -> str:
+    """Serialize a parsed value back to a string for stdout."""
+    if fmt is OutputFormat.JSON:
+        return json.dumps(value, indent=2, ensure_ascii=False)
+    if fmt is OutputFormat.XML:
+        assert isinstance(value, ET.Element)
+        return ET.tostring(value, encoding="unicode")
+    return str(value)
+
+
+async def _run(args: argparse.Namespace) -> int:
+    prompt = args.prompt if args.prompt is not None else sys.stdin.read()
+    prompt = prompt.strip()
+    if not prompt:
+        print("error: empty prompt", file=sys.stderr)
+        return 2
+
+    config = GemxConfig(
+        profile_dir=args.profile_dir,
+        headless=not args.headful,
+        response_timeout_s=args.response_timeout,
+    )
+    try:
+        async with Gemx(config) as gemx:
+            result = await gemx.ask(prompt, args.format)
+    except GemxError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(_render(result, args.format))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``gemx`` console script."""
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.INFO if args.verbose else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+    return asyncio.run(_run(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gemx/client.py

@@ -0,0 +1,235 @@
+"""Drive the Gemini web UI via Playwright.
+
+This is a formalized version of a hack that drives ``gemini.google.com/app`` as
+if it were an API. The non-obvious parts (and why this exists):
+
+* **Input** must go through ``document.execCommand('insertText')``. Gemini's
+  editor is Quill, which keeps its own document model and ignores DOM surgery,
+  Playwright ``fill()``, and synthetic ``InputEvent``s — those leave the model
+  empty and the turn errors with "I encountered an error". ``execCommand`` fires
+  the trusted ``beforeinput``/``input`` pair Quill honors, exactly like a paste.
+* **The response** lives in ``message-content .markdown`` (not a bare
+  ``.markdown``), and Gemini re-mounts / empties that node after streaming, so we
+  retain the *peak* text seen rather than reading the DOM once at the end.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from playwright.async_api import Page, async_playwright
+
+from .errors import InputError, ResponseTimeoutError
+from .formats import OutputFormat, format_instruction, parse_output
+
+logger = logging.getLogger("gemx")
+
+GEMINI_URL = "https://gemini.google.com/app"
+INPUT_SELECTOR = '.ql-editor[contenteditable="true"]'
+SEND_SELECTOR = 'button[aria-label="Send message"]'
+RESPONSE_SELECTOR = "message-content .markdown"
+
+_INSERT_TEXT_JS = """(text) => {
+    const editor = document.querySelector('.ql-editor[contenteditable="true"]');
+    if (!editor) return false;
+    editor.focus();
+    const sel = window.getSelection();
+    sel.removeAllRanges();
+    const range = document.createRange();
+    range.selectNodeContents(editor);
+    range.collapse(false);
+    sel.addRange(range);
+    return document.execCommand('insertText', false, text);
+}"""
+
+_LONGEST_RESPONSE_JS = """(args) => {
+    const [selector, initialCount] = args;
+    const els = document.querySelectorAll(selector);
+    if (els.length <= initialCount) return '';
+    let best = '';
+    els.forEach(el => {
+        const t = el.innerText || el.textContent || '';
+        if (t.length > best.length) best = t;
+    });
+    return best;
+}"""
+
+_DISMISS_WELCOME_JS = """() => {
+    const buttons = Array.from(document.querySelectorAll('button, [role="button"]'));
+    for (const btn of buttons) {
+        const text = btn.innerText || btn.textContent || '';
+        if (text.match(/continue|get started|skip|next|accept|try gemini/i)) {
+            btn.click();
+            return true;
+        }
+    }
+    return false;
+}"""
+
+
+@dataclass(frozen=True, slots=True)
+class GemxConfig:  # pylint: disable=too-many-instance-attributes
+    """Tunables for a :class:`Gemx` session."""
+
+    profile_dir: Path
+    headless: bool = True
+    nav_timeout_ms: int = 60_000
+    input_timeout_ms: int = 30_000
+    response_timeout_s: int = 180
+    stabilization_timeout_s: int = 120
+    poll_interval_s: int = 2
+    viewport_width: int = 1280
+    viewport_height: int = 720
+    user_agent: str = (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+    )
+    launch_args: tuple[str, ...] = field(
+        default=(
+            "--disable-blink-features=AutomationControlled",
+            "--disable-dev-shm-usage",
+            "--no-sandbox",
+            "--disable-setuid-sandbox",
+        )
+    )
+
+
+class Gemx:
+    """A Gemini web-UI session.
+
+    Use as an async context manager so the browser is cleaned up::
+
+        async with Gemx(GemxConfig(profile_dir=Path("~/.gemx/profile"))) as gemx:
+            data = await gemx.ask("List 3 fruits", OutputFormat.JSON)
+    """
+
+    def __init__(self, config: GemxConfig) -> None:
+        self._config = config
+
+    async def ask(
+        self, prompt: str, fmt: OutputFormat = OutputFormat.JSON
+    ) -> Any:
+        """Send ``prompt`` to Gemini and return its reply parsed as ``fmt``.
+
+        The format instruction is appended to the prompt so Gemini emits the
+        requested shape.
+
+        Raises:
+            InputError: If the prompt could not be entered.
+            ResponseTimeoutError: If no response arrived in time.
+            ResponseParseError: If the reply could not be parsed as ``fmt``.
+        """
+        full_prompt = f"{prompt}\n\n{format_instruction(fmt)}"
+        raw = await self.ask_raw(full_prompt)
+        return parse_output(raw, fmt)
+
+    async def ask_raw(self, prompt: str) -> str:
+        """Send ``prompt`` verbatim and return Gemini's raw reply text."""
+        cfg = self._config
+        profile = cfg.profile_dir.expanduser()
+        async with async_playwright() as p:
+            context = await p.chromium.launch_persistent_context(
+                str(profile),
+                headless=cfg.headless,
+                args=list(cfg.launch_args),
+                user_agent=cfg.user_agent,
+                viewport={
+                    "width": cfg.viewport_width,
+                    "height": cfg.viewport_height,
+                },
+            )
+            try:
+                page = (
+                    context.pages[0] if context.pages else await context.new_page()
+                )
+                await self._navigate(page)
+                await self._enter_prompt(page, prompt)
+                await self._submit(page)
+                return await self._await_response(page)
+            finally:
+                await context.close()
+
+    async def _navigate(self, page: Page) -> None:
+        cfg = self._config
+        await page.goto(GEMINI_URL, wait_until="load", timeout=cfg.nav_timeout_ms)
+        await page.wait_for_load_state("domcontentloaded")
+        await page.wait_for_load_state("networkidle", timeout=30_000)
+        await page.wait_for_timeout(5_000)
+
+        body_text = await page.evaluate("() => document.body.innerText || ''")
+        if "welcome to gemini" in body_text.lower():
+            logger.info("welcome screen detected; dismissing")
+            dismissed = await page.evaluate(_DISMISS_WELCOME_JS)
+            await page.wait_for_timeout(3_000 if dismissed else 1_000)
+
+        await page.wait_for_selector(INPUT_SELECTOR, timeout=cfg.input_timeout_ms)
+
+    async def _enter_prompt(self, page: Page, prompt: str) -> None:
+        await page.click(INPUT_SELECTOR)
+        ok: bool = await page.evaluate(_INSERT_TEXT_JS, prompt)
+        entered = (await page.locator(INPUT_SELECTOR).first.inner_text()).strip()
+        logger.info("entered prompt: ok=%s chars=%d", ok, len(entered))
+        if not ok or not entered:
+            raise InputError("Quill did not accept the prompt text")
+
+    async def _submit(self, page: Page) -> None:
+        await page.wait_for_selector(
+            SEND_SELECTOR, timeout=self._config.input_timeout_ms
+        )
+        await page.click(SEND_SELECTOR)
+
+    async def _await_response(self, page: Page) -> str:
+        cfg = self._config
+        initial = await page.evaluate(
+            "(s) => document.querySelectorAll(s).length", RESPONSE_SELECTOR
+        )
+
+        # Wait for a new response node to appear.
+        elapsed = 0
+        while elapsed < cfg.response_timeout_s:
+            count = await page.evaluate(
+                "(s) => document.querySelectorAll(s).length", RESPONSE_SELECTOR
+            )
+            if count > initial:
+                break
+            await asyncio.sleep(cfg.poll_interval_s)
+            elapsed += cfg.poll_interval_s
+        else:
+            raise ResponseTimeoutError(
+                f"No response node after {cfg.response_timeout_s}s"
+            )
+
+        # Stream until the longest node's text stops growing, retaining the peak.
+        best = ""
+        last_len = 0
+        stable = 0
+        waited = 0
+        while waited < cfg.stabilization_timeout_s:
+            await asyncio.sleep(cfg.poll_interval_s)
+            waited += cfg.poll_interval_s
+            current: str = await page.evaluate(
+                _LONGEST_RESPONSE_JS, [RESPONSE_SELECTOR, initial]
+            )
+            if len(current) > len(best):
+                best = current
+            if len(current) > last_len:
+                last_len = len(current)
+                stable = 0
+            elif best:
+                stable += 1
+                if stable >= 2 and len(best) > 0:
+                    break
+
+        if not best:
+            raise ResponseTimeoutError("Response node never produced text")
+        return best
+
+    async def __aenter__(self) -> Gemx:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        return None

gemx/errors.py

@@ -0,0 +1,19 @@
+"""Exceptions raised by Gemx."""
+
+from __future__ import annotations
+
+
+class GemxError(Exception):
+    """Base class for all Gemx errors."""
+
+
+class InputError(GemxError):
+    """The prompt could not be entered into Gemini's editor."""
+
+
+class ResponseTimeoutError(GemxError):
+    """Gemini did not produce a response within the configured window."""
+
+
+class ResponseParseError(GemxError):
+    """Gemini responded, but the payload could not be parsed for the format."""

gemx/formats.py

@@ -0,0 +1,103 @@
+"""Output formats Gemx can request from Gemini.
+
+The chosen format is injected into the prompt as an instruction and also drives
+how Gemx extracts the structured payload from Gemini's reply.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from enum import StrEnum
+from typing import Any
+from xml.etree import ElementTree as ET
+
+
+class OutputFormat(StrEnum):
+    """Structured output formats Gemx understands."""
+
+    JSON = "json"
+    XML = "xml"
+    TXT = "txt"
+
+    @classmethod
+    def from_str(cls, value: str) -> OutputFormat:
+        """Parse a format name case-insensitively.
+
+        Raises:
+            ValueError: If ``value`` is not a supported format.
+        """
+        try:
+            return cls(value.strip().lower())
+        except ValueError as exc:
+            supported = ", ".join(f.value for f in cls)
+            raise ValueError(
+                f"Unsupported output format {value!r}; expected one of: {supported}"
+            ) from exc
+
+
+def format_instruction(fmt: OutputFormat) -> str:
+    """Return the prompt instruction that asks Gemini for ``fmt`` output."""
+    if fmt is OutputFormat.JSON:
+        return (
+            "Respond with a single valid JSON object only. Do not include prose, "
+            "markdown fences, or commentary outside the JSON."
+        )
+    if fmt is OutputFormat.XML:
+        return (
+            "Respond with a single well-formed XML document only. Do not include "
+            "prose, markdown fences, or commentary outside the XML."
+        )
+    return (
+        "Respond with plain text only. Do not include markdown fences, JSON, or "
+        "XML."
+    )
+
+
+def _strip_fences(text: str) -> str:
+    """Strip a leading format label and surrounding markdown code fences."""
+    text = text.strip()
+    text = re.sub(r"^(JSON|XML)\s*\n?", "", text, flags=re.IGNORECASE)
+    fence = re.search(r"```[a-zA-Z]*\s*(.*?)```", text, flags=re.DOTALL)
+    if fence:
+        return fence.group(1).strip()
+    return text
+
+
+def _clean_json_text(text: str) -> str:
+    """Best-effort repair of common JSON quirks in LLM output."""
+    text = text.strip()
+    text = re.sub(r",\s*([}\]])", r"\1", text)
+    return text
+
+
+def parse_output(text: str, fmt: OutputFormat) -> Any:
+    """Extract a structured value from Gemini's raw reply for ``fmt``.
+
+    JSON yields a ``dict``/``list``, XML yields an
+    :class:`xml.etree.ElementTree.Element`, and TXT yields the cleaned ``str``.
+
+    Raises:
+        ValueError: If the payload cannot be parsed as ``fmt``.
+    """
+    cleaned = _strip_fences(text)
+
+    if fmt is OutputFormat.TXT:
+        return cleaned
+
+    if fmt is OutputFormat.JSON:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}") + 1
+        candidate = cleaned[start:end] if start != -1 and end != 0 else cleaned
+        try:
+            return json.loads(_clean_json_text(candidate))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Could not parse JSON from response: {exc}") from exc
+
+    start = cleaned.find("<")
+    end = cleaned.rfind(">") + 1
+    candidate = cleaned[start:end] if start != -1 and end != 0 else cleaned
+    try:
+        return ET.fromstring(candidate)
+    except ET.ParseError as exc:
+        raise ValueError(f"Could not parse XML from response: {exc}") from exc

gemx-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: gemx
+Version: 0.1.0
+Summary: Drive the Gemini web UI from Python via Playwright
+Project-URL: Homepage, https://github.com/ra0x3/gemx
+Project-URL: Repository, https://github.com/ra0x3/gemx
+Project-URL: Issues, https://github.com/ra0x3/gemx/issues
+Author: ra0x3
+Maintainer: ra0x3
+License: MIT
+License-File: LICENSE
+Keywords: automation,browser,gemini,llm,playwright,scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: playwright>=1.49
+Description-Content-Type: text/markdown
+
+# Gemx
+
+**Drive the Gemini web UI from Python.** A play on "Gemini" — Gemx treats
+`gemini.google.com` as if it were an API, using Playwright to enter a prompt,
+submit it, and capture the structured reply.
+
+It exists because the obvious approaches don't work: Gemini's editor is
+[Quill](https://quilljs.com/), which keeps its own document model and ignores
+DOM surgery, Playwright `fill()`, and synthetic input events — those leave the
+model empty and the turn errors with *"I encountered an error."* Gemx injects
+text via `execCommand('insertText')` (the same trusted input pipeline a manual
+paste uses), reads the reply from `message-content .markdown`, and retains the
+*peak* streamed text because Gemini re-mounts the response node mid-stream.
+
+## Install
+
+```bash
+uv add gemx
+# Playwright needs a browser the first time:
+uv run playwright install chromium
+```
+
+## CLI
+
+```bash
+# JSON (default)
+gemx "List 3 NBA teams as a JSON array"
+
+# XML
+gemx --format xml "Describe the solar system as XML"
+
+# Plain text, reading the prompt from stdin
+echo "Summarize the plot of Dune in one sentence" | gemx --format txt
+
+# Watch the browser while it works
+gemx --headful --verbose "Hello there"
+```
+
+The chosen `--format` (`json`, `xml`, or `txt`) is appended to the prompt as an
+instruction *and* drives how Gemx parses the reply.
+
+| Option | Description |
+| --- | --- |
+| `-f, --format {json,xml,txt}` | Output format (default: `json`). |
+| `-p, --profile-dir PATH` | Chrome profile dir (default: `~/.gemx/profile`). |
+| `--headful` | Show the browser window. |
+| `--response-timeout SECONDS` | Wait for a response to start (default: 180). |
+| `-v, --verbose` | Log progress to stderr. |
+
+## Library
+
+```python
+import asyncio
+from pathlib import Path
+from gemx import Gemx, GemxConfig, OutputFormat
+
+
+async def main() -> None:
+    config = GemxConfig(profile_dir=Path("~/.gemx/profile"))
+    async with Gemx(config) as gemx:
+        data = await gemx.ask("List 3 fruits as JSON", OutputFormat.JSON)
+        print(data)
+
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Gemx drives a real, signed-in Gemini session. Point `--profile-dir` at a Chrome
+profile that is already logged into your Google account (run once with
+`--headful` to sign in); subsequent runs reuse that profile.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run mypy
+uv run pylint src/gemx
+uv run pytest
+```
+
+The browser-console debugging scripts used to discover and verify the current
+Gemini selectors live in [`tests/scripts/`](tests/scripts/).
+
+## License
+
+MIT © ra0x3 — [Stonehedge Labs](https://github.com/stonehedgelabs)

gemx-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gemx/__init__.py,sha256=5_lo6aTFGHef-6oOs7l0V-WL3NjXy9fy2-VHYjUpYi8,595
+gemx/cli.py,sha256=AEZOVzovGtd3fTcZhaNFv1pcGHWlg2rx1SJ_d6tiJbQ,3232
+gemx/client.py,sha256=b3sprX_Esv5nhI0I-97pCw-Ki-0nzJhEvu8jcsMGd4I,8572
+gemx/errors.py,sha256=e0h-gLm9NR_FZpYErdzwOOfSLhuo28c1ryJUSrJXQlo,470
+gemx/formats.py,sha256=d9jTaKV9oaGa6iruiM95sHMxWf5nGgZ99NsaGhtcR4k,3308
+gemx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gemx-0.1.0.dist-info/METADATA,sha256=3IxArBlr1CGkfHWIFUGsf2ZtyTxCoKCW6GNm9umWMx8,3393
+gemx-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gemx-0.1.0.dist-info/entry_points.txt,sha256=NMTvUjDGNXOZOarNBSA93tpiLgyb-sARANVi0lHHDV4,39
+gemx-0.1.0.dist-info/licenses/LICENSE,sha256=jd9AQQBkmyuf_q0BrYApY8xmkzWxEKlYDCSmlh6a31c,1080
+gemx-0.1.0.dist-info/RECORD,,

gemx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

gemx-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gemx = gemx.cli:main

gemx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ra0x3 / Stonehedge Labs
+
+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.