gemcode 0.2.2__py3-none-any.whl

gemcode/computer_use/browser_computer.py

@@ -0,0 +1,275 @@
+"""
+Playwright-backed browser automation (ADK ComputerUse).
+
+This provides an ADK `BaseComputer` implementation so the LLM can call
+computer-use tools like `click_at`, `type_text_at`, and `navigate`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+from typing import Optional
+from typing import Sequence
+from typing import Tuple
+
+from google.adk.tools.computer_use.base_computer import BaseComputer
+from google.adk.tools.computer_use.base_computer import ComputerEnvironment
+from google.adk.tools.computer_use.base_computer import ComputerState
+
+
+@dataclass(frozen=True)
+class BrowserComputerConfig:
+  headless: bool = True
+  viewport_width: int = 1280
+  viewport_height: int = 720
+  navigation_timeout_ms: int = 30_000
+
+
+class BrowserComputer(BaseComputer):
+  def __init__(
+    self,
+    *,
+    headless: bool = True,
+    viewport_size: Tuple[int, int] = (1280, 720),
+    navigation_timeout_ms: int = 30_000,
+  ):
+    self._cfg = BrowserComputerConfig(
+      headless=headless,
+      viewport_width=viewport_size[0],
+      viewport_height=viewport_size[1],
+      navigation_timeout_ms=navigation_timeout_ms,
+    )
+    self._playwright = None
+    self._browser = None
+    self._context = None
+    self._page = None
+
+  async def initialize(self) -> None:
+    if self._page is not None:
+      return
+    try:
+      from playwright.async_api import async_playwright
+    except ImportError as e:
+      raise RuntimeError(
+        "Browser computer requires Playwright. Install `playwright` and run `playwright install`."
+      ) from e
+
+    self._playwright = await async_playwright().start()
+    self._browser = await self._playwright.chromium.launch(headless=self._cfg.headless)
+    self._context = await self._browser.new_context(
+      viewport={"width": self._cfg.viewport_width, "height": self._cfg.viewport_height}
+    )
+    self._page = await self._context.new_page()
+    self._page.set_default_navigation_timeout(self._cfg.navigation_timeout_ms)
+
+  async def close(self) -> None:
+    if self._page is not None:
+      try:
+        await self._context.close()
+      except Exception:
+        pass
+    if self._browser is not None:
+      try:
+        await self._browser.close()
+      except Exception:
+        pass
+    if self._playwright is not None:
+      try:
+        await self._playwright.stop()
+      except Exception:
+        pass
+    self._playwright = None
+    self._browser = None
+    self._context = None
+    self._page = None
+
+  async def environment(self) -> ComputerEnvironment:
+    return ComputerEnvironment.ENVIRONMENT_BROWSER
+
+  async def screen_size(self) -> tuple[int, int]:
+    await self.initialize()
+    return (self._cfg.viewport_width, self._cfg.viewport_height)
+
+  async def current_state(self) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    screenshot = await self._page.screenshot(type="png", full_page=False)
+    url = self._page.url
+    return ComputerState(screenshot=screenshot, url=url)
+
+  async def open_web_browser(self) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    # Use about:blank to establish a page; LLM can navigate afterwards.
+    await self._page.goto("about:blank")
+    return await self.current_state()
+
+  async def click_at(self, x: int, y: int) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.mouse.click(x, y)
+    return await self.current_state()
+
+  async def hover_at(self, x: int, y: int) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.mouse.move(x, y)
+    await self._page.wait_for_timeout(150)
+    return await self.current_state()
+
+  async def type_text_at(
+    self,
+    x: int,
+    y: int,
+    text: str,
+    press_enter: bool = True,
+    clear_before_typing: bool = True,
+  ) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.mouse.click(x, y)
+    if clear_before_typing:
+      # MVP clear behavior: select all + backspace.
+      await self._page.keyboard.press("Control+A")
+      await self._page.keyboard.press("Backspace")
+    await self._page.keyboard.type(text)
+    if press_enter:
+      await self._page.keyboard.press("Enter")
+    return await self.current_state()
+
+  async def scroll_document(
+    self, direction: Literal["up", "down", "left", "right"]
+  ) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    magnitude = 600
+    if direction == "up":
+      dx, dy = 0, -magnitude
+    elif direction == "down":
+      dx, dy = 0, magnitude
+    elif direction == "left":
+      dx, dy = -magnitude, 0
+    else:
+      dx, dy = magnitude, 0
+    await self._page.mouse.wheel(dx=dx, dy=dy)
+    await self._page.wait_for_timeout(250)
+    return await self.current_state()
+
+  async def scroll_at(
+    self,
+    x: int,
+    y: int,
+    direction: Literal["up", "down", "left", "right"],
+    magnitude: int,
+  ) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.mouse.move(x, y)
+    if direction == "up":
+      dx, dy = 0, -abs(magnitude)
+    elif direction == "down":
+      dx, dy = 0, abs(magnitude)
+    elif direction == "left":
+      dx, dy = -abs(magnitude), 0
+    else:
+      dx, dy = abs(magnitude), 0
+    await self._page.mouse.wheel(dx=dx, dy=dy)
+    await self._page.wait_for_timeout(250)
+    return await self.current_state()
+
+  async def wait(self, seconds: int) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.wait_for_timeout(max(1, int(seconds)) * 1000)
+    return await self.current_state()
+
+  async def go_back(self) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.go_back()
+    await self._page.wait_for_timeout(250)
+    return await self.current_state()
+
+  async def go_forward(self) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.go_forward()
+    await self._page.wait_for_timeout(250)
+    return await self.current_state()
+
+  async def search(self) -> ComputerState:
+    # Home page for web search.
+    return await self.navigate("https://www.google.com")
+
+  async def navigate(self, url: str) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.goto(url, wait_until="load")
+    await self._page.wait_for_timeout(250)
+    return await self.current_state()
+
+  async def key_combination(self, keys: list[str]) -> ComputerState:
+    """
+    Press a key combination.
+
+    ADK can pass values like `["control+c"]`. We parse `control+c` into a
+    Playwright modifier sequence.
+    """
+    await self.initialize()
+    assert self._page is not None
+
+    mod_map = {
+      "control": "Control",
+      "ctrl": "Control",
+      "shift": "Shift",
+      "alt": "Alt",
+      "option": "Alt",
+      "meta": "Meta",
+      "command": "Meta",
+      "cmd": "Meta",
+      "super": "Meta",
+    }
+
+    def _press_key_combo(combo: str) -> None:
+      parts = combo.lower().replace(" ", "").split("+")
+      if len(parts) == 1:
+        return self._page.keyboard.press(parts[0])
+      mods = parts[:-1]
+      key = parts[-1]
+      # Playwright: down(mod) + press(key) + up(mod)
+      async def _run():
+        for m in mods:
+          pw = mod_map.get(m, None)
+          if pw:
+            await self._page.keyboard.down(pw)
+        await self._page.keyboard.press(key)
+        for m in reversed(mods):
+          pw = mod_map.get(m, None)
+          if pw:
+            await self._page.keyboard.up(pw)
+
+      return _run()
+
+    for k in keys:
+      res = _press_key_combo(k)
+      if hasattr(res, "__await__"):
+        await res
+      else:
+        # `press` already awaited by Playwright; noop.
+        pass
+
+    return await self.current_state()
+
+  async def drag_and_drop(
+    self, x: int, y: int, destination_x: int, destination_y: int
+  ) -> ComputerState:
+    await self.initialize()
+    assert self._page is not None
+    await self._page.mouse.move(x, y)
+    await self._page.mouse.down()
+    await self._page.mouse.move(destination_x, destination_y)
+    await self._page.mouse.up()
+    await self._page.wait_for_timeout(250)
+    return await self.current_state()
+

gemcode/config.py

@@ -0,0 +1,247 @@
+"""Environment and CLI configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _split_csv(s: str | None) -> list[str]:
+  if not s:
+    return []
+  return [x.strip() for x in s.split(",") if x.strip()]
+
+
+def _opt_positive_int(name: str) -> int | None:
+  v = os.environ.get(name)
+  if v is None or not str(v).strip():
+    return None
+  n = int(str(v).strip())
+  return n if n > 0 else None
+
+
+def _opt_int(name: str) -> int | None:
+  """Optional int from env, allowing 0 / negative values."""
+  v = os.environ.get(name)
+  if v is None or not str(v).strip():
+    return None
+  return int(str(v).strip())
+
+
+def _truthy_env(name: str, *, default: bool = False) -> bool:
+  v = os.environ.get(name)
+  if v is None:
+    return default
+  return v.lower() in ("1", "true", "yes", "on")
+
+
+def token_budget_invocation_reset() -> dict:
+  """Reset per-user-message token budget tracker (matches new `query()` in Claude)."""
+  import time
+
+  t = int(time.time() * 1000)
+  return {
+      "gemcode:bt_cc": 0,
+      "gemcode:bt_ld": 0,
+      "gemcode:bt_lg": 0,
+      "gemcode:bt_t0": t,
+      "gemcode:bt_base_total_tokens": -1,
+      "gemcode:bt_token_budget_stop": False,
+  }
+
+
+@dataclass
+class GemCodeConfig:
+  """Runtime options (CLI + env)."""
+
+  project_root: Path
+  model: str = field(default_factory=lambda: os.environ.get("GEMCODE_MODEL", "gemini-2.5-flash"))
+  # Model mode: fast|balanced|quality|auto
+  model_mode: str = field(
+    default_factory=lambda: os.environ.get("GEMCODE_MODEL_MODE", "fast")
+  )
+  model_quality: str | None = field(
+    default_factory=lambda: os.environ.get("GEMCODE_MODEL_QUALITY")
+  )
+  model_balanced: str | None = field(
+    default_factory=lambda: os.environ.get("GEMCODE_MODEL_BALANCED")
+  )
+  # Model family routing: choose between the "primary" model ids (GEMCODE_MODEL*
+  # fields) and 2.5 alternatives (GEMCODE_MODEL_ALT* fields).
+  #
+  # - `auto`: heuristic chooses primary for complex prompts, alt for simple
+  # - `primary`: always use primary ids
+  # - `alt`: always use 2.5 ids (GEMCODE_MODEL_ALT*)
+  model_family_mode: str = field(
+    default_factory=lambda: os.environ.get("GEMCODE_MODEL_FAMILY_MODE", "auto")
+  )
+  model_alt: str | None = field(
+    default_factory=lambda: os.environ.get("GEMCODE_MODEL_ALT")
+  )
+  model_alt_quality: str | None = field(
+    default_factory=lambda: os.environ.get("GEMCODE_MODEL_ALT_QUALITY")
+  )
+  model_alt_balanced: str | None = field(
+    default_factory=lambda: os.environ.get("GEMCODE_MODEL_ALT_BALANCED")
+  )
+  permission_mode: str = field(
+    default_factory=lambda: os.environ.get("GEMCODE_PERMISSION_MODE", "default")
+  )
+  allow_commands: frozenset[str] | None = None
+  yes_to_all: bool = False
+  # When enabled, GemCode will ask for user confirmation in the *same run*
+  # (HITL) before mutating tools / computer-use tools execute.
+  #
+  # Default behavior is controlled in the CLI:
+  # - If `GEMCODE_INTERACTIVE_PERMISSION_ASK` is set, we honor it.
+  # - Otherwise we enable when stdin is a TTY and `--yes` is not provided.
+  interactive_permission_ask: bool = field(
+    default_factory=lambda: _truthy_env(
+      "GEMCODE_INTERACTIVE_PERMISSION_ASK", default=False
+    )
+  )
+  max_content_items: int = field(
+    default_factory=lambda: int(os.environ.get("GEMCODE_MAX_CONTENT_ITEMS", "40"))
+  )
+  # ADK RunConfig.max_llm_calls (model↔tool iterations per user message); None = SDK default (500).
+  max_llm_calls: int | None = field(default_factory=lambda: _opt_positive_int("GEMCODE_MAX_LLM_CALLS"))
+  # Hard stop before next LLM call when cumulative usage_metadata totals exceed this.
+  max_session_tokens: int | None = field(
+    default_factory=lambda: _opt_positive_int("GEMCODE_MAX_SESSION_TOKENS")
+  )
+  # Optional per-turn style budget for continuation logging (see query/token_budget.py).
+  token_budget: int | None = field(default_factory=lambda: _opt_positive_int("GEMCODE_TOKEN_BUDGET"))
+  # Enables persistent memory via ADK context integration (file-backed).
+  enable_memory: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_ENABLE_MEMORY", default=False)
+  )
+
+  # Modality toggles (tool injection + routing).
+  enable_deep_research: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_ENABLE_DEEP_RESEARCH", default=False)
+  )
+  enable_embeddings: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_ENABLE_EMBEDDINGS", default=False)
+  )
+
+  # Deep research model id used when routing selects deep research.
+  model_deep_research: str = field(
+    default_factory=lambda: os.environ.get(
+      "GEMCODE_MODEL_DEEP_RESEARCH", "travel_explore"
+    )
+  )
+
+  # Embeddings model id used by embeddings-powered tools/memory (if enabled).
+  embeddings_model: str = field(
+    default_factory=lambda: os.environ.get(
+      "GEMCODE_EMBEDDINGS_MODEL", "models/gemini-embedding-2-preview"
+    )
+  )
+
+  # Deep research: Google Maps grounding is optional because it can be
+  # incompatible with other built-in tools (e.g., google_search) in the same
+  # request depending on the model/tooling layer.
+  enable_maps_grounding: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_ENABLE_MAPS_GROUNDING", default=False)
+  )
+
+  # Computer use (ADK ComputerUseToolset) enable/disable; default is off for safety.
+  enable_computer_use: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_ENABLE_COMPUTER_USE", default=False)
+  )
+
+  # Audio mode (Gemini Live models). Only fully supported via `gemcode live-audio`
+  # in this MVP.
+  enable_audio: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_ENABLE_AUDIO", default=False)
+  )
+  model_audio_live: str = field(
+    default_factory=lambda: os.environ.get(
+      "GEMCODE_MODEL_AUDIO_LIVE", "gemini-3.1-flash-live-preview"
+    )
+  )
+  model_computer_use: str = field(
+    default_factory=lambda: os.environ.get(
+      "GEMCODE_MODEL_COMPUTER_USE",
+      "gemini-2.5-computer-use-preview-10-2025",
+    )
+  )
+
+  # Capability routing: auto|research|embeddings|computer|audio|all
+  capability_mode: str = field(
+    default_factory=lambda: os.environ.get("GEMCODE_CAPABILITY_MODE", "auto")
+  )
+
+  # Gemini 3 "tool context circulation" (built-in tools + function tools
+  # combination). Controls when we set ToolConfig(include_server_side_tool_invocations=True).
+  #
+  # - deep_research: only when enable_deep_research is enabled
+  # - always: enable for Gemini 3.x regardless of deep-research toggle
+  # - never: disable always
+  # - auto: alias for deep_research
+  tool_combination_mode: str = field(
+    default_factory=lambda: os.environ.get(
+      "GEMCODE_TOOL_COMBINATION_MODE", "deep_research"
+    )
+  )
+
+  # Set by CLI when the user explicitly provides --model. Used to prevent
+  # role-based routing from overriding their selection.
+  model_overridden: bool = False
+
+  # Gemini thinking controls (Claude-like intent, Gemini-specific knobs).
+  #
+  # Claude Code enables thinking by default and only forces disable/budgets
+  # when explicitly configured. We match that by returning "None" unless the
+  # user asks for explicit overrides below.
+  #
+  # - Gemini 3.x: supports `thinkingLevel` (can't fully disable).
+  # - Gemini 2.5: supports `thinkingBudget` (0 disables for models that allow it).
+  disable_thinking: bool = field(
+    default_factory=lambda: _truthy_env("GEMCODE_DISABLE_THINKING", default=False)
+  )
+  include_thought_summaries: bool = field(
+    default_factory=lambda: _truthy_env(
+      "GEMCODE_INCLUDE_THOUGHT_SUMMARIES", default=False
+    )
+  )
+  thinking_level: str | None = field(
+    default_factory=lambda: os.environ.get("GEMCODE_THINKING_LEVEL")
+  )
+  thinking_budget: int | None = field(
+    default_factory=lambda: _opt_int("GEMCODE_THINKING_BUDGET")
+  )
+
+  def __post_init__(self) -> None:
+    self.project_root = self.project_root.resolve()
+    if self.allow_commands is None:
+      env = os.environ.get("GEMCODE_ALLOW_COMMANDS")
+      if env:
+        self.allow_commands = frozenset(_split_csv(env))
+      else:
+        self.allow_commands = frozenset(
+          (
+            "pytest",
+            "python3",
+            "python",
+            "pip",
+            "pip3",
+            "npm",
+            "npx",
+            "git",
+            "ruff",
+            "uv",
+            "cargo",
+            "go",
+          )
+        )
+
+
+def load_dotenv_optional() -> None:
+  try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+  except ImportError:
+    pass

gemcode/interactions.py

@@ -0,0 +1,15 @@
+"""
+Gemini Interactions API (optional durable / server-side history).
+
+The ADK `LlmRequest` includes `previous_interaction_id` for chaining interactions.
+Wiring GemCode to Interactions API can reduce client-side history size for long
+sessions. Implementation is deferred: enable when your `google-adk` version and
+deployment target require it, following:
+https://ai.google.dev/gemini-api/docs/interactions
+
+Planned integration points:
+- Store `previous_interaction_id` in `.gemcode/session_meta.json` per session.
+- Pass through Runner/App configuration when ADK exposes a stable hook for your stack.
+"""
+
+from __future__ import annotations

gemcode/invoke.py

@@ -0,0 +1,151 @@
+"""
+Single user turn (Claude Code: inner path ≈ `query()` invocation per message).
+
+CLI and tests call `run_turn` with a Runner already bound to app + session service.
+"""
+
+from __future__ import annotations
+
+import sys
+from threading import Lock
+
+from google.adk.agents.run_config import RunConfig
+from google.adk.runners import Runner
+from google.genai import types
+
+
+_HITL_PROMPT_LOCK = Lock()
+
+
+async def run_turn(
+    runner: Runner,
+    *,
+    user_id: str,
+    session_id: str,
+    prompt: str,
+    max_llm_calls: int | None = None,
+    cfg: "GemCodeConfig | None" = None,
+) -> list:
+  """Execute one user message; collect all Events (caller aggregates text)."""
+
+  collected: list = []
+
+  run_config = (
+    RunConfig(max_llm_calls=max_llm_calls) if max_llm_calls is not None else None
+  )
+
+  # Apply token-budget reset only once per user turn, even if we must resume
+  # across multiple ADK tool-confirmation handoffs.
+  state_delta = None
+  if cfg is not None and cfg.token_budget:
+    from gemcode.config import token_budget_invocation_reset
+
+    state_delta = token_budget_invocation_reset()
+
+  # The first message is plain user text.
+  current_message = types.Content(role="user", parts=[types.Part(text=prompt)])
+
+  async def _await_runner_events(*, next_message: types.Content, do_reset: bool):
+    kwargs = dict(
+      user_id=user_id,
+      session_id=session_id,
+      new_message=next_message,
+    )
+    if run_config is not None:
+      kwargs["run_config"] = run_config
+    if do_reset and state_delta is not None:
+      kwargs["state_delta"] = state_delta
+    events: list = []
+    async for event in runner.run_async(**kwargs):
+      events.append(event)
+    return events
+
+  REQUEST_CONFIRMATION_FC = "adk_request_confirmation"
+
+  def _get_confirmation_requests(events: list) -> list[types.FunctionCall]:
+    out: list[types.FunctionCall] = []
+    for ev in events:
+      try:
+        for fc in ev.get_function_calls() or []:
+          if getattr(fc, "name", None) == REQUEST_CONFIRMATION_FC:
+            out.append(fc)
+      except Exception:
+        continue
+    return out
+
+  def _extract_hint_and_tool(fc: types.FunctionCall) -> tuple[str, str]:
+    # generate_request_confirmation_event() builds:
+    # - args.originalFunctionCall.{name,args,...}
+    # - args.toolConfirmation.{hint, ...}
+    tool_name = "unknown_tool"
+    hint = ""
+    try:
+      args = getattr(fc, "args", None) or {}
+      orig = args.get("originalFunctionCall") or {}
+      tool_name = orig.get("name") or tool_name
+      tc = args.get("toolConfirmation") or {}
+      hint = tc.get("hint") or ""
+    except Exception:
+      pass
+    return tool_name, hint
+
+  def _prompt_yes_no(prompt_text: str) -> bool:
+    with _HITL_PROMPT_LOCK:
+      while True:
+        ans = input(prompt_text).strip().lower()
+        if ans in ("y", "yes"):
+          return True
+        if ans in ("", "n", "no"):
+          return False
+        print("Please answer 'y' or 'n'.")
+
+  # Runner handoff loop: if tools request confirmations, we pause here to ask
+  # HITL, then send back function responses so ADK can re-execute the tools.
+  do_reset = True
+  while True:
+    events = await _await_runner_events(
+      next_message=current_message, do_reset=do_reset
+    )
+    collected.extend(events)
+
+    confirmation_fcs = _get_confirmation_requests(events)
+    if not confirmation_fcs:
+      break
+
+    # If interactive ask is disabled, auto-reject to avoid hanging on stdin.
+    interactive_enabled = bool(
+      getattr(cfg, "interactive_permission_ask", False)
+      and hasattr(sys.stdin, "isatty")
+      and sys.stdin.isatty()
+    )
+
+    parts: list[types.Part] = []
+    for fc in confirmation_fcs:
+      tool_name, hint = _extract_hint_and_tool(fc)
+      if interactive_enabled:
+        suffix = f"\n  Hint: {hint}" if hint else ""
+        ok = _prompt_yes_no(
+          f"\n[gemcode HITL] Approve tool call '{tool_name}'? [y/N]{suffix}\n> "
+        )
+      else:
+        ok = False
+        print(
+          f"[gemcode HITL] Tool confirmation requested for '{tool_name}', but interactive-ask is disabled; auto-rejecting.",
+          file=sys.stderr,
+        )
+
+      parts.append(
+        types.Part(
+          function_response=types.FunctionResponse(
+            name=REQUEST_CONFIRMATION_FC,
+            id=getattr(fc, "id", None),
+            response={"confirmed": ok},
+          )
+        )
+      )
+
+    current_message = types.Content(role="user", parts=parts)
+    # Subsequent resumes must not re-reset token budgets.
+    do_reset = False
+
+  return collected