grip-browser 0.1.0__py3-none-any.whl

grip/__init__.py

@@ -0,0 +1,20 @@
+from grip.browser import Browser
+from grip.compression.summarizer import Element, PageSnapshot
+from grip.errors.types import BrowserError, ErrorType, GripError, RecoveryAction
+from grip.page import Screenshot
+from grip.trace import Trace, TraceEntry
+
+__all__ = [
+    "Browser",
+    "PageSnapshot",
+    "Element",
+    "BrowserError",
+    "ErrorType",
+    "GripError",
+    "RecoveryAction",
+    "Screenshot",
+    "Trace",
+    "TraceEntry",
+]
+
+__version__ = "0.1.0"

grip/adapters/anthropic.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+try:
+    import anthropic as anthropic
+except ImportError:
+    anthropic = None
+
+from grip.adapters.base import LLMResponse, ToolCall
+
+
+class AnthropicAdapter:
+    def __init__(
+        self, api_key: str | None = None, model: str = "claude-opus-4-7"
+    ) -> None:
+        if anthropic is None:
+            raise ImportError("pip install grip-browser[anthropic]")
+        self._client = anthropic.AsyncAnthropic(api_key=api_key)
+        self._model = model
+
+    async def complete(self, messages: list[dict], tools: list[dict]) -> LLMResponse:
+        kwargs = {"model": self._model, "max_tokens": 4096, "messages": messages}
+        if tools:
+            kwargs["tools"] = tools
+        response = await self._client.messages.create(**kwargs)
+        if response.stop_reason == "tool_use":
+            for block in response.content:
+                if hasattr(block, "type") and block.type == "tool_use":
+                    return LLMResponse(
+                        content=None,
+                        tool_call=ToolCall(name=block.name, arguments=block.input),
+                    )
+        text = "".join(block.text for block in response.content if hasattr(block, "text"))
+        return LLMResponse(content=text, tool_call=None)

grip/adapters/base.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class ToolCall:
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass
+class LLMResponse:
+    content: str | None
+    tool_call: ToolCall | None
+
+
+@runtime_checkable
+class LLMAdapter(Protocol):
+    async def complete(
+        self,
+        messages: list[dict],
+        tools: list[dict],
+    ) -> LLMResponse: ...

grip/adapters/openai.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+import json
+from typing import Any
+
+try:
+    import openai as openai
+except ImportError:
+    openai = None
+
+from grip.adapters.base import LLMResponse, ToolCall
+
+
+class OpenAIAdapter:
+    def __init__(self, api_key: str | None = None, model: str = "gpt-4o") -> None:
+        if openai is None:
+            raise ImportError("pip install grip-browser[openai]")
+        self._client = openai.AsyncOpenAI(api_key=api_key)
+        self._model = model
+
+    async def complete(self, messages: list[dict], tools: list[dict]) -> LLMResponse:
+        kwargs: dict[str, Any] = {"model": self._model, "messages": messages}
+        if tools:
+            kwargs["tools"] = tools
+        response = await self._client.chat.completions.create(**kwargs)
+        choice = response.choices[0]
+        msg = choice.message
+        if msg.tool_calls:
+            tc = msg.tool_calls[0]
+            return LLMResponse(
+                content=None,
+                tool_call=ToolCall(
+                    name=tc.function.name,
+                    arguments=json.loads(tc.function.arguments),
+                ),
+            )
+        return LLMResponse(content=msg.content, tool_call=None)

grip/browser.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+import asyncio
+import json
+from typing import TYPE_CHECKING
+
+from grip.cdp.engine import CDPEngine
+from grip.cdp.launcher import ChromeLauncher
+from grip.page import Page
+from grip.trace import Trace
+
+if TYPE_CHECKING:
+    from grip.adapters.base import LLMAdapter
+
+
+async def fetch_tab_ws_url(port: int) -> str:
+    import urllib.request
+    import time
+
+    def _do_fetch() -> list:
+        with urllib.request.urlopen(
+            f"http://localhost:{port}/json", timeout=2
+        ) as resp:
+            return json.loads(resp.read())
+
+    deadline = time.monotonic() + 10.0
+    while time.monotonic() < deadline:
+        try:
+            tabs = await asyncio.to_thread(_do_fetch)
+            for tab in tabs:
+                if tab.get("type") == "page":
+                    return tab["webSocketDebuggerUrl"]
+        except Exception:
+            pass
+        await asyncio.sleep(0.2)
+    raise RuntimeError(f"No Chrome tab found on port {port}")
+
+
+class Browser:
+    def __init__(self, llm: "LLMAdapter | None" = None, headless: bool = True) -> None:
+        self._llm = llm
+        self._headless = headless
+        self._launcher: ChromeLauncher | None = None
+        self._engine: CDPEngine | None = None
+        self.trace = Trace()
+
+    async def __aenter__(self) -> "Browser":
+        self._launcher = ChromeLauncher()
+        port = self._launcher.launch(headless=self._headless)
+        ws_url = await fetch_tab_ws_url(port)
+        self._engine = CDPEngine()
+        await self._engine.connect(ws_url)
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()
+
+    async def open(self, url: str) -> Page:
+        if not self._engine:
+            self._launcher = ChromeLauncher()
+            port = self._launcher.launch(headless=self._headless)
+            ws_url = await fetch_tab_ws_url(port)
+            self._engine = CDPEngine()
+            await self._engine.connect(ws_url)
+
+        if not url.startswith(("http", "about:", "data:", "file:", "blob:")):
+            url = "https://" + url
+
+        await self._engine.send("Page.navigate", {"url": url})
+        await self._engine.send("Page.enable")
+
+        load_event = asyncio.Event()
+
+        def on_load(params):
+            load_event.set()
+
+        self._engine.on("Page.loadEventFired", on_load)
+        try:
+            await asyncio.wait_for(load_event.wait(), timeout=30.0)
+        except asyncio.TimeoutError:
+            pass
+        finally:
+            self._engine.off("Page.loadEventFired", on_load)
+
+        return Page(engine=self._engine, trace=self.trace)
+
+    async def run(self, goal: str, url: str) -> "RunResult":
+        from grip.runner import Runner
+        page = await self.open(url)
+        runner = Runner(llm=self._llm, page=page, trace=self.trace)
+        return await runner.run(goal)
+
+    async def close(self) -> None:
+        if self._engine:
+            await self._engine.disconnect()
+            self._engine = None
+        if self._launcher:
+            self._launcher.terminate()
+            self._launcher = None

grip/cdp/engine.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+import asyncio
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+import websockets
+
+logger = logging.getLogger(__name__)
+
+
+class CDPEngine:
+    def __init__(self) -> None:
+        self._ws: websockets.WebSocketClientProtocol | None = None
+        self._id = 0
+        self._pending: dict[int, asyncio.Future] = {}
+        self._listeners: dict[str, list[Callable]] = {}
+        self._receive_task: asyncio.Task | None = None
+
+    def _next_id(self) -> int:
+        self._id += 1
+        return self._id
+
+    async def connect(self, url: str) -> None:
+        self._ws = await websockets.connect(url, max_size=50 * 1024 * 1024)
+        self._receive_task = asyncio.create_task(self._receive_loop())
+
+    async def disconnect(self) -> None:
+        if self._receive_task:
+            self._receive_task.cancel()
+            try:
+                await self._receive_task
+            except asyncio.CancelledError:
+                pass
+        if self._ws:
+            await self._ws.close()
+            self._ws = None
+
+    async def send(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        msg_id = self._next_id()
+        fut: asyncio.Future = asyncio.get_running_loop().create_future()
+        self._pending[msg_id] = fut
+        payload = json.dumps({"id": msg_id, "method": method, "params": params or {}})
+        await self._ws.send(payload)
+        try:
+            return await asyncio.wait_for(fut, timeout=30.0)
+        except asyncio.TimeoutError:
+            self._pending.pop(msg_id, None)
+            raise TimeoutError(f"CDP command {method} timed out")
+
+    def on(self, event: str, callback: Callable) -> None:
+        self._listeners.setdefault(event, []).append(callback)
+
+    def off(self, event: str, callback: Callable) -> None:
+        listeners = self._listeners.get(event, [])
+        if callback in listeners:
+            listeners.remove(callback)
+
+    async def _receive_loop(self) -> None:
+        try:
+            async for raw in self._ws:
+                msg = json.loads(raw)
+                if "id" in msg:
+                    fut = self._pending.pop(msg["id"], None)
+                    if fut and not fut.done():
+                        if "error" in msg:
+                            fut.set_exception(RuntimeError(msg["error"]["message"]))
+                        else:
+                            fut.set_result(msg.get("result", {}))
+                elif "method" in msg:
+                    for cb in self._listeners.get(msg["method"], []):
+                        try:
+                            cb(msg.get("params", {}))
+                        except Exception:
+                            logger.exception("CDP listener error for %s", msg["method"])
+        except Exception:
+            logger.debug("CDP receive loop ended")

grip/cdp/launcher.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+_CHROME_CANDIDATES = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/usr/bin/google-chrome",
+    "/usr/bin/chromium-browser",
+    "/usr/bin/chromium",
+]
+
+
+def find_chrome() -> str | None:
+    if exe := os.environ.get("CHROME_EXECUTABLE"):
+        return exe
+    for candidate in _CHROME_CANDIDATES:
+        if Path(candidate).exists():
+            return candidate
+    for name in ("google-chrome", "chromium", "chromium-browser"):
+        try:
+            result = subprocess.run(["which", name], capture_output=True, text=True)
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except FileNotFoundError:
+            pass
+    return None
+
+
+class ChromeLauncher:
+    def __init__(self) -> None:
+        exe = find_chrome()
+        if not exe:
+            raise RuntimeError(
+                "Chrome/Chromium not found. Install Chrome or set CHROME_EXECUTABLE."
+            )
+        self.executable = exe
+        self._process: subprocess.Popen | None = None
+        self._user_data_dir: str | None = None
+
+    def launch(self, headless: bool = True) -> int:
+        self._user_data_dir = tempfile.mkdtemp(prefix="grip_chrome_")
+        args = [
+            self.executable,
+            "--remote-debugging-port=0",
+            f"--user-data-dir={self._user_data_dir}",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-extensions",
+        ]
+        if headless:
+            args.append("--headless=new")
+        self._process = subprocess.Popen(
+            args,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        port = self._read_port()
+        return port
+
+    def _read_port(self) -> int:
+        import time
+        port_file = Path(self._user_data_dir) / "DevToolsActivePort"
+        deadline = time.monotonic() + 10.0
+        while time.monotonic() < deadline:
+            if port_file.exists():
+                text = port_file.read_text().strip()
+                return int(text.split("\n")[0])
+            time.sleep(0.05)
+        raise RuntimeError("Timed out waiting for Chrome DevTools port")
+
+    def terminate(self) -> None:
+        if self._process:
+            self._process.terminate()
+            self._process.wait(timeout=5)
+            self._process = None
+        if self._user_data_dir:
+            import shutil
+            shutil.rmtree(self._user_data_dir, ignore_errors=True)
+            self._user_data_dir = None

grip/cdp/shadow.py

@@ -0,0 +1,142 @@
+DISCOVER_ELEMENTS_JS = """
+(function() {
+  const results = [];
+  let idx = 0;
+
+  const INTERACTIVE_TAGS = new Set([
+    'a','button','input','select','textarea','details','summary'
+  ]);
+  const INTERACTIVE_ROLES = new Set([
+    'button','link','checkbox','radio','menuitem','tab','textbox',
+    'combobox','listbox','option','switch','treeitem','slider'
+  ]);
+
+  function collectElements(root, inShadow) {
+    const walker = document.createTreeWalker(
+      root,
+      NodeFilter.SHOW_ELEMENT,
+      null
+    );
+    let node = walker.currentNode;
+    while (node) {
+      const el = node;
+      if (!el.tagName) { node = walker.nextNode(); continue; }
+      const tag = el.tagName.toLowerCase();
+      const role = el.getAttribute('role') || el.getAttribute('aria-role') || '';
+      const ariaHidden = el.getAttribute('aria-hidden') === 'true';
+      const style = window.getComputedStyle(el);
+      const hidden = (
+        style.display === 'none' ||
+        style.visibility === 'hidden' ||
+        parseFloat(style.opacity) === 0 ||
+        ariaHidden ||
+        el.offsetWidth === 0 ||
+        el.offsetHeight === 0
+      );
+
+      if (!hidden && (INTERACTIVE_TAGS.has(tag) || INTERACTIVE_ROLES.has(role))) {
+        const rect = el.getBoundingClientRect();
+        results.push({
+          index: idx++,
+          tag: tag,
+          role: role || tag,
+          text: (el.innerText || el.value || el.getAttribute('aria-label') || '').trim().slice(0, 120),
+          placeholder: el.getAttribute('placeholder') || null,
+          inShadowDom: inShadow,
+          cx: Math.round(rect.left + rect.width / 2),
+          cy: Math.round(rect.top + rect.height / 2),
+        });
+      }
+
+      if (el.shadowRoot) {
+        collectElements(el.shadowRoot, true);
+      }
+      node = walker.nextNode();
+    }
+  }
+
+  collectElements(document.body, false);
+  return results;
+})();
+"""
+
+CLICK_ELEMENT_JS = """
+function(index) {
+  const elements = [];
+  const INTERACTIVE_TAGS = new Set([
+    'a','button','input','select','textarea','details','summary'
+  ]);
+  const INTERACTIVE_ROLES = new Set([
+    'button','link','checkbox','radio','menuitem','tab','textbox',
+    'combobox','listbox','option','switch','treeitem','slider'
+  ]);
+
+  function collect(root) {
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, null);
+    let node = walker.currentNode;
+    while (node) {
+      const el = node;
+      if (!el.tagName) { node = walker.nextNode(); continue; }
+      const tag = el.tagName.toLowerCase();
+      const role = el.getAttribute('role') || '';
+      if (INTERACTIVE_TAGS.has(tag) || INTERACTIVE_ROLES.has(role)) {
+        const style = window.getComputedStyle(el);
+        const hidden = (style.display === 'none' || style.visibility === 'hidden');
+        if (!hidden) elements.push(el);
+      }
+      if (el.shadowRoot) collect(el.shadowRoot);
+      node = walker.nextNode();
+    }
+  }
+
+  collect(document.body);
+  if (index < elements.length) {
+    elements[index].click();
+    return true;
+  }
+  return false;
+}
+"""
+
+TYPE_ELEMENT_JS = """
+function(index, text) {
+  const elements = [];
+  const INPUT_TAGS = new Set(['input','textarea']);
+
+  function collect(root) {
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, null);
+    let node = walker.currentNode;
+    while (node) {
+      const el = node;
+      if (!el.tagName) { node = walker.nextNode(); continue; }
+      const tag = el.tagName.toLowerCase();
+      if (INPUT_TAGS.has(tag) || el.isContentEditable) {
+        const style = window.getComputedStyle(el);
+        if (style.display !== 'none') elements.push(el);
+      }
+      if (el.shadowRoot) collect(el.shadowRoot);
+      node = walker.nextNode();
+    }
+  }
+
+  collect(document.body);
+  if (index < elements.length) {
+    const el = elements[index];
+    el.focus();
+    el.value = '';
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+    el.value = text;
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    return true;
+  }
+  return false;
+}
+"""
+
+PAGE_TEXT_JS = """
+(function() {
+  const main = document.querySelector('main, [role="main"]') || document.body;
+  return (main.innerText || main.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 8000);
+})();
+"""

grip/compression/cache.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+import hashlib
+from grip.compression.summarizer import Element
+
+
+def _cache_key(tag: str, text: str) -> str:
+    return hashlib.md5(f"{tag}:{text}".encode()).hexdigest()
+
+
+class ElementCache:
+    def __init__(self) -> None:
+        self._store: dict[str, Element] = {}
+
+    def store(self, element: Element) -> None:
+        key = _cache_key(element.tag, element.text)
+        self._store[key] = element
+
+    def get(self, tag: str, text: str) -> Element | None:
+        return self._store.get(_cache_key(tag, text))
+
+    def invalidate(self) -> None:
+        self._store.clear()
+
+    def store_many(self, elements: list[Element]) -> None:
+        for el in elements:
+            self.store(el)

grip/compression/diff.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+import hashlib
+from grip.compression.summarizer import PageSnapshot
+
+
+def _snapshot_fingerprint(snap: PageSnapshot) -> str:
+    element_sig = "|".join(f"{el.tag}:{el.text}" for el in snap.elements)
+    raw = f"{snap.url}||{snap.text_content[:500]}||{element_sig}"
+    return hashlib.md5(raw.encode()).hexdigest()
+
+
+class SnapshotDiff:
+    def __init__(self) -> None:
+        self._last_fingerprint: str | None = None
+
+    def has_changed(self, snapshot: PageSnapshot) -> bool:
+        fp = _snapshot_fingerprint(snapshot)
+        return fp != self._last_fingerprint
+
+    def record(self, snapshot: PageSnapshot) -> None:
+        self._last_fingerprint = _snapshot_fingerprint(snapshot)

grip/compression/summarizer.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+from grip.security.sanitizer import RawElement
+
+try:
+    import tiktoken
+    _ENC = tiktoken.get_encoding("cl100k_base")
+
+    def _count_tokens(text: str) -> int:
+        return len(_ENC.encode(text))
+except Exception:
+    def _count_tokens(text: str) -> int:
+        return len(text) // 4
+
+
+_TAG_ABBREV = {
+    "button": "btn",
+    "input": "inp",
+    "a": "lnk",
+    "select": "sel",
+    "textarea": "inp",
+}
+
+
+@dataclass
+class Element:
+    index: int
+    snapshot_version: int
+    tag: str
+    role: str
+    text: str
+    placeholder: str | None
+    in_shadow_dom: bool
+    cx: int
+    cy: int
+
+
+@dataclass
+class PageSnapshot:
+    version: int
+    url: str
+    title: str
+    elements: list[Element]
+    text_content: str
+    tokens_estimated: int
+    changed_from_previous: bool = True
+
+
+class Summarizer:
+    def build(
+        self,
+        version: int,
+        url: str,
+        title: str,
+        raw_elements: list[RawElement],
+        page_text: str,
+    ) -> PageSnapshot:
+        elements = [
+            Element(
+                index=i,
+                snapshot_version=version,
+                tag=el.tag,
+                role=el.role,
+                text=el.text,
+                placeholder=el.placeholder,
+                in_shadow_dom=el.in_shadow_dom,
+                cx=el.cx,
+                cy=el.cy,
+            )
+            for i, el in enumerate(raw_elements)
+        ]
+        text_content = page_text.strip()
+        formatted = self._build_format_str(url, title, elements, text_content)
+        tokens = _count_tokens(formatted)
+        return PageSnapshot(
+            version=version,
+            url=url,
+            title=title,
+            elements=elements,
+            text_content=text_content,
+            tokens_estimated=tokens,
+        )
+
+    def format(self, snapshot: PageSnapshot) -> str:
+        return self._build_format_str(
+            snapshot.url, snapshot.title, snapshot.elements, snapshot.text_content
+        )
+
+    def _build_format_str(
+        self, url: str, title: str, elements: list[Element], text: str
+    ) -> str:
+        lines = [f"PAGE: {title}", f"URL: {url}"]
+        if elements:
+            lines.append("INTERACTIVE:")
+            for el in elements:
+                abbrev = _TAG_ABBREV.get(el.tag, el.tag[:3])
+                desc = el.text or el.placeholder or el.role
+                lines.append(f"  [{abbrev}:{el.index}] {desc!r}")
+        if text:
+            lines.append("CONTENT:")
+            lines.append(f"  {text[:2000]}")
+        return "\n".join(lines)

grip/errors/__init__.py

@@ -0,0 +1,3 @@
+from grip.errors.types import BrowserError, ErrorType, GripError, RecoveryAction
+
+__all__ = ["BrowserError", "ErrorType", "GripError", "RecoveryAction"]