gemx 0.1.0__tar.gz

gemx-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+venv/
+uv.lock
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Playwright profile data (never commit a logged-in session)
+*.jimi-profile/
+profile/
+
+# OS
+.DS_Store

gemx-0.1.0/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.

gemx-0.1.0/PKG-INFO

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

@@ -0,0 +1,89 @@
+# 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/pyproject.toml

@@ -0,0 +1,94 @@
+[project]
+name = "gemx"
+version = "0.1.0"
+description = "Drive the Gemini web UI from Python via Playwright"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "ra0x3" }]
+maintainers = [{ name = "ra0x3" }]
+keywords = ["gemini", "playwright", "automation", "llm", "browser", "scraping"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "playwright>=1.49",
+]
+
+[project.urls]
+Homepage = "https://github.com/ra0x3/gemx"
+Repository = "https://github.com/ra0x3/gemx"
+Issues = "https://github.com/ra0x3/gemx/issues"
+
+[project.scripts]
+gemx = "gemx.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13",
+    "ruff>=0.8",
+    "pylint>=3.3",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gemx"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "A", "C4", "SIM", "RUF"]
+ignore = ["A003"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["gemx"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_any_generics = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+files = ["src/gemx"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = "playwright.*"
+ignore_missing_imports = true
+
+[tool.pylint.main]
+py-version = "3.12"
+source-roots = ["src"]
+
+[tool.pylint.format]
+max-line-length = 88
+
+[tool.pylint."messages control"]
+disable = [
+    "missing-module-docstring",
+    "too-few-public-methods",
+    "duplicate-code",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

gemx-0.1.0/src/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-0.1.0/src/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())