anybrowser 0.1.0__py3-none-any.whl

anybrowser/__init__.py

@@ -0,0 +1,64 @@
+"""AnyBrowser -- a pluggable browser-automation and agent runtime.
+
+Three interfaces, each with an entry-point registry, each with a conformance
+suite you can run against your own implementation:
+
+* :class:`anybrowser.core.BrowserEngine` -- drive a browser (Chrome, Safari, yours)
+* :class:`anybrowser.daemon.DaemonTransport` -- how clients reach the daemon
+* :class:`anybrowser.models.ModelProvider` -- where completions come from
+
+    from anybrowser import open_engine
+
+    async with await open_engine("chrome") as engine:
+        await engine.navigate("https://example.com")
+        page = await engine.snapshot()
+        print(page.title, len(page.elements), "elements")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# NOT `from .core import engines`: the `anybrowser.engines` SUBPACKAGE binds
+# that same name on this module as soon as anything imports it, silently
+# replacing the registry with the package. In a source tree it survives on
+# import-order luck; from an installed wheel it does not. Import the
+# registry under a name nothing else claims.
+from .core import BrowserEngine, Capability, SyncEngine
+from .core.errors import AnyBrowserError
+from .core.registry import engines as engine_registry
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AnyBrowserError",
+    "BrowserEngine",
+    "Capability",
+    "SyncEngine",
+    "__version__",
+    "available_engines",
+    "engines",
+    "open_engine",
+]
+
+
+async def open_engine(name: str, /, **options: Any) -> BrowserEngine:
+    """Construct and start the named engine.
+
+    ``name`` is a key in the ``anybrowser.engines`` entry-point group. The returned engine
+    is already started and is also an async context manager, so both of these
+    work::
+
+        engine = await open_engine("chrome")
+        async with await open_engine("chrome") as engine: ...
+    """
+    cls = engine_registry.get(name)
+    await cls.probe()
+    engine: BrowserEngine = cls(**options)
+    await engine.start()
+    return engine
+
+
+def available_engines() -> list[str]:
+    """Every registered engine name, installed plugins included."""
+    return engine_registry.names()

anybrowser/agent/__init__.py

@@ -0,0 +1,32 @@
+"""The agent runtime: decide what to do, then do it.
+
+    runner = AgentRunner(engine, LLMPlanner(provider, model="claude-sonnet-5"))
+    result = await runner.run("find the pricing page")
+
+Swapping the :class:`Planner` changes what kind of agent this is; the tools,
+engines and daemon underneath do not move.
+"""
+
+from .llm_planner import SYSTEM_PROMPT, LLMPlanner
+from .planner import Decision, Observation, Planner, Step
+from .runner import AgentRunner, RunConfig, RunResult, StopReason, render_history
+from .tool import Tool, ToolContext, ToolResult
+from .tools import default_tools
+
+__all__ = [
+    "SYSTEM_PROMPT",
+    "AgentRunner",
+    "Decision",
+    "LLMPlanner",
+    "Observation",
+    "Planner",
+    "RunConfig",
+    "RunResult",
+    "Step",
+    "StopReason",
+    "Tool",
+    "ToolContext",
+    "ToolResult",
+    "default_tools",
+    "render_history",
+]

anybrowser/agent/llm_planner.py

@@ -0,0 +1,233 @@
+"""A planner that asks a model what to do next.
+
+The default planner. It renders the goal, the page, the history and the tool
+schemas into one prompt, and parses a single JSON decision back.
+
+Two choices here are deliberate and worth defending.
+
+**JSON in the response, not provider tool-calling.** Tool-call formats differ
+per provider in ways no wrapper survives intact, and several models AnyBrowser
+should support have none at all. Asking for one JSON object works everywhere and
+keeps :class:`~anybrowser.models.provider.ModelProvider` small.
+
+**`narrative` is required.** A model that emits no reasoning tokens still has to
+say why. A history reading "clicked, clicked, clicked" cannot be debugged by
+anyone -- including the model itself on the next step.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from ..core.errors import ModelError
+from ..models.provider import ImagePart, Message, ModelProvider, Role
+from .planner import Decision, Observation, Planner
+from .runner import render_history
+from .tool import Tool
+
+__all__ = ["SYSTEM_PROMPT", "LLMPlanner"]
+
+SYSTEM_PROMPT = """\
+You are driving a web browser to accomplish a goal. You see the page as a list \
+of interactive elements, each with a handle, plus a screenshot when one is \
+available.
+
+Choose exactly ONE action per turn. Reply with one JSON object and nothing else:
+
+{"tool": "<tool name>", "arguments": {...}, "narrative": "<why, in one sentence>"}
+
+For example, to click the element listed as `handle=3:12`:
+
+{"tool": "click", "arguments": {"handle": "3:12"}, "narrative": "this is the login button"}
+
+When the goal is achieved, reply instead with:
+
+{"done": true, "answer": "<what you found, or what you did>", "narrative": "<why you are finished>"}
+
+Rules that matter:
+
+- Every element below is listed as `handle=<id>`. Pass that id EXACTLY, copied \
+character for character. It is an opaque id such as "3:12" -- never the label, \
+the tag, or anything you read off the screenshot.
+- Act only on handles in the CURRENT listing. Handles from earlier turns are \
+stale and will be refused.
+- A result marked [no effect] means the action changed nothing. Doing it again \
+will change nothing again. Try something else: scroll, look, or pick a \
+different element.
+- A result marked [failed] means the action could not run at all. Read the \
+reason before choosing.
+- "narrative" is required, always, and must say why you chose this action -- \
+not what the action is.
+- Do not claim the goal is done without evidence in the page that it is.\
+"""
+
+
+class LLMPlanner(Planner):
+    """Ask a model for the next action."""
+
+    name = "llm"
+
+    def __init__(
+        self,
+        provider: ModelProvider,
+        *,
+        model: str,
+        max_elements: int = 60,
+        temperature: float = 0.0,
+        max_tokens: int = 800,
+        system_prompt: str = SYSTEM_PROMPT,
+    ) -> None:
+        self._provider = provider
+        self._model = model
+        self._max_elements = max_elements
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+        self._system_prompt = system_prompt
+        #: Accumulated across a run, so a caller can meter what an agent cost.
+        self.total_cost_usd = 0.0
+        self.total_tokens = 0
+
+    # ------------------------------------------------------------------ #
+    # Prompting                                                           #
+    # ------------------------------------------------------------------ #
+
+    def _render_page(self, observation: Observation) -> str:
+        page = observation.snapshot
+        lines = [f"URL: {page.url}", f"Title: {page.title}", "", "Elements:"]
+        if not page.elements:
+            lines.append("  (none found — try scrolling, or the page may still be loading)")
+        for element in page.elements[: self._max_elements]:
+            # `description` already starts with the tag or role, so printing
+            # both made the line read as `[2:0] a 'a Learn more'` -- and a model
+            # will reach for the quoted text as the identifier. Give the handle
+            # its own labelled column and print the label alone.
+            kind = element.role or element.tag
+            label = element.label or element.placeholder or element.value or "(no label)"
+            detail = f"handle={element.handle}  <{kind}>  {label!r}"
+            if element.value and element.value != label:
+                detail += f"  value={element.value!r}"
+            if element.disabled:
+                detail += "  (disabled)"
+            lines.append("  " + detail)
+        if len(page.elements) > self._max_elements:
+            hidden = len(page.elements) - self._max_elements
+            lines.append(f"  … and {hidden} more not shown")
+        return "\n".join(lines)
+
+    def _render_tools(self, tools: Sequence[Tool]) -> str:
+        return "\n".join(
+            f"- {tool.name}: {tool.description}\n  arguments: "
+            f"{json.dumps(tool.parameters.get('properties', {}))}"
+            for tool in tools
+        )
+
+    def _build_messages(self, observation: Observation, tools: Sequence[Tool]) -> list[Message]:
+        parts = [
+            f"GOAL: {observation.goal}",
+            "",
+            "TOOLS:",
+            self._render_tools(tools),
+            "",
+            "PAGE:",
+            self._render_page(observation),
+        ]
+        if observation.history:
+            parts += ["", "WHAT YOU HAVE DONE:", render_history(observation.history)]
+        if observation.notes:
+            parts += ["", "NOTES:", *(f"- {n}" for n in observation.notes)]
+        parts += ["", f"Step {observation.step_index + 1}. Choose one action."]
+
+        images: list[ImagePart] = []
+        if observation.screenshot is not None and self._provider.supports_images(self._model):
+            images.append(
+                ImagePart(
+                    data=observation.screenshot.data,
+                    media_type=f"image/{observation.screenshot.format}",
+                )
+            )
+        return [
+            Message(role=Role.SYSTEM, text=self._system_prompt),
+            Message(role=Role.USER, text="\n".join(parts), images=images),
+        ]
+
+    # ------------------------------------------------------------------ #
+    # Deciding                                                            #
+    # ------------------------------------------------------------------ #
+
+    async def decide(self, observation: Observation, tools: Sequence[Tool]) -> Decision:
+        messages = self._build_messages(observation, tools)
+        completion = await self._provider.complete(
+            messages,
+            model=self._model,
+            temperature=self._temperature,
+            max_tokens=self._max_tokens,
+        )
+        self.total_cost_usd += completion.usage.cost_usd
+        self.total_tokens += completion.usage.input_tokens + completion.usage.output_tokens
+        return self._parse(completion.text, tools)
+
+    def _parse(self, text: str, tools: Sequence[Tool]) -> Decision:
+        payload = _extract_json(text)
+        if payload is None:
+            raise ModelError(f"planner did not return JSON: {text[:300]!r}")
+
+        narrative = str(payload.get("narrative") or "").strip()
+        if payload.get("done"):
+            return Decision(
+                tool="",
+                arguments={},
+                # A model that finishes without saying why still has to say
+                # something; refusing here would fail a successful run over
+                # a missing sentence.
+                narrative=narrative or "the goal appears to be met",
+                done=True,
+                answer=str(payload.get("answer") or ""),
+            )
+
+        tool = str(payload.get("tool") or "").strip()
+        if not tool:
+            raise ModelError(f"planner named no tool: {text[:300]!r}")
+        known = {t.name for t in tools}
+        if tool not in known:
+            raise ModelError(f"planner chose unknown tool {tool!r}; available: {sorted(known)}")
+
+        arguments = payload.get("arguments")
+        if not isinstance(arguments, dict):
+            arguments = {}
+        return Decision(
+            tool=tool,
+            arguments=arguments,
+            narrative=narrative or f"calling {tool}",
+        )
+
+
+_FENCE = re.compile(r"```(?:json)?\s*(.*?)```", re.S)
+
+
+def _extract_json(text: str) -> dict[str, Any] | None:
+    """Find the JSON object in a model's reply.
+
+    Models wrap JSON in prose and fences no matter how firmly the prompt asks
+    them not to. Being lenient here costs nothing; being strict costs a run.
+    """
+    candidates: list[str] = []
+    fenced = _FENCE.search(text)
+    if fenced:
+        candidates.append(fenced.group(1))
+    candidates.append(text)
+    start = text.find("{")
+    end = text.rfind("}")
+    if start != -1 and end > start:
+        candidates.append(text[start : end + 1])
+
+    for candidate in candidates:
+        try:
+            parsed = json.loads(candidate.strip())
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+    return None

anybrowser/agent/memory/__init__.py

@@ -0,0 +1 @@
+"""AnyBrowser subpackage."""

anybrowser/agent/planner.py

@@ -0,0 +1,75 @@
+"""``Planner`` -- decides the next action.
+
+Swapping the planner is how you change what kind of agent this is. The default
+one is an LLM reading a screenshot and a snapshot; a scripted planner replaying a
+recorded workflow, or a heuristic one, implements the same two methods and runs
+on the same executor, tools and engines.
+"""
+
+from __future__ import annotations
+
+import abc
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..core.types import Screenshot, Snapshot
+from .tool import Tool, ToolResult
+
+__all__ = ["Decision", "Observation", "Planner"]
+
+
+@dataclass(frozen=True, slots=True)
+class Observation:
+    """Everything the planner is allowed to see this step."""
+
+    goal: str
+    snapshot: Snapshot
+    screenshot: Screenshot | None = None
+    history: Sequence[Step] = ()
+    notes: Sequence[str] = ()
+    step_index: int = 0
+    extra: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    """One chosen action.
+
+    ``narrative`` is required and must be a human explanation of *why*, not a
+    restatement of the tool call. Models with no visible reasoning still have to
+    produce one; a run whose history reads "clicked, clicked, clicked" cannot be
+    debugged by anyone, including the model itself on the next step.
+    """
+
+    tool: str
+    arguments: Mapping[str, Any]
+    narrative: str
+    done: bool = False
+    answer: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.narrative.strip():
+            raise ValueError("Decision.narrative is required")
+
+
+@dataclass(frozen=True, slots=True)
+class Step:
+    """One completed (decision, result) pair, as history renders it."""
+
+    decision: Decision
+    result: ToolResult
+
+
+class Planner(abc.ABC):
+    """Chooses the next tool call."""
+
+    #: Registry name, if published as a plugin.
+    name: str = ""
+
+    @abc.abstractmethod
+    async def decide(self, observation: Observation, tools: Sequence[Tool]) -> Decision: ...
+
+    async def reflect(self, observation: Observation, step: Step) -> None:
+        """Optional hook after each step, for memory or a stuck detector."""
+        return None

anybrowser/agent/runner.py

@@ -0,0 +1,262 @@
+"""The loop: observe, decide, act, remember.
+
+    runner = AgentRunner(engine, planner)
+    result = await runner.run("find the pricing page and read the top tier")
+
+Deliberately small. Everything that decides *quality* lives in the planner and
+in perception; this file's whole job is to be an honest, interruptible loop that
+never lies to the planner about what happened.
+
+Three properties it guarantees, each of which is a failure mode somewhere else:
+
+**It re-observes before every decision.** A planner reasoning about a snapshot
+taken three actions ago is reasoning about a page that no longer exists, and
+its handles are stale by definition.
+
+**It records no-ops as no-ops.** ``ToolResult.changed`` goes into history
+verbatim. A history that renders "clicked, success" for a click that hit an
+invisible overlay teaches the model that clicking again is progress, and it
+will do that until the budget runs out.
+
+**It stops.** A budget, a stop signal, and a repetition breaker. Long-horizon
+agents do not fail by crashing; they fail by continuing.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+
+from ..core.engine import BrowserEngine
+from ..core.errors import AnyBrowserError
+from ..core.types import Screenshot
+from .planner import Decision, Observation, Planner, Step
+from .tool import Tool, ToolContext, ToolResult
+from .tools import default_tools
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["AgentRunner", "RunConfig", "RunResult", "StopReason"]
+
+
+class StopReason(str):
+    """Why a run ended. A plain string subclass so it renders itself in logs."""
+
+    DONE = "done"
+    BUDGET = "budget_exhausted"
+    STOPPED = "stopped"
+    STUCK = "stuck"
+    ERROR = "error"
+
+
+@dataclass(slots=True)
+class RunConfig:
+    """Limits. All of them exist because something ran away without them."""
+
+    #: Hard ceiling on actions. The single most important safety valve.
+    max_steps: int = 40
+    #: Wall-clock ceiling, in seconds. Zero disables it.
+    max_seconds: float = 600.0
+    #: Give the planner a screenshot alongside the snapshot.
+    include_screenshot: bool = True
+    #: How many consecutive actions may change nothing before the run is called
+    #: stuck. Counts any action, not just repeats -- see AgentRunner.run for why
+    #: repetition is the wrong thing to measure. Four leaves room for a genuine
+    #: retry and a look in between.
+    repeat_limit: int = 4
+    #: Confirm before a mutating tool runs. Returning False refuses the action;
+    #: the planner is told, and can choose something else.
+    confirm: Callable[[Decision], bool] | None = None
+
+
+@dataclass(slots=True)
+class RunResult:
+    goal: str
+    answer: str = ""
+    stop_reason: str = StopReason.DONE
+    steps: list[Step] = field(default_factory=list)
+    error: str = ""
+    elapsed: float = 0.0
+
+    @property
+    def ok(self) -> bool:
+        return self.stop_reason == StopReason.DONE
+
+    @property
+    def step_count(self) -> int:
+        return len(self.steps)
+
+
+class AgentRunner:
+    """Drives a planner against a browser until it is done or out of budget."""
+
+    def __init__(
+        self,
+        engine: BrowserEngine,
+        planner: Planner,
+        *,
+        tools: Sequence[Tool] | None = None,
+        config: RunConfig | None = None,
+    ) -> None:
+        self._engine = engine
+        self._planner = planner
+        self._tools = list(tools) if tools is not None else default_tools()
+        self._config = config or RunConfig()
+        self._by_name = {tool.name: tool for tool in self._tools}
+        self._stop = asyncio.Event()
+
+    @property
+    def tools(self) -> Sequence[Tool]:
+        return tuple(self._tools)
+
+    def stop(self) -> None:
+        """Ask the run to finish after the current action.
+
+        Cooperative rather than a cancellation, because killing an agent
+        mid-action leaves the page in a state nobody recorded.
+        """
+        self._stop.set()
+
+    async def run(self, goal: str, *, notes: Sequence[str] = ()) -> RunResult:
+        started = time.monotonic()
+        result = RunResult(goal=goal)
+        context = ToolContext(engine=self._engine)
+        recent: list[tuple[str, str]] = []
+
+        for index in range(self._config.max_steps):
+            if self._stop.is_set():
+                result.stop_reason = StopReason.STOPPED
+                break
+            if self._config.max_seconds and time.monotonic() - started > self._config.max_seconds:
+                result.stop_reason = StopReason.BUDGET
+                break
+
+            try:
+                observation = await self._observe(goal, result.steps, notes, index)
+            except AnyBrowserError as exc:
+                result.stop_reason, result.error = StopReason.ERROR, str(exc)
+                break
+            context.snapshot = observation.snapshot
+
+            try:
+                decision = await self._planner.decide(observation, self._tools)
+            except AnyBrowserError as exc:
+                result.stop_reason, result.error = StopReason.ERROR, str(exc)
+                break
+
+            if decision.done:
+                result.answer = decision.answer
+                result.stop_reason = StopReason.DONE
+                result.steps.append(
+                    Step(
+                        decision=decision, result=ToolResult(ok=True, changed=False, summary="done")
+                    )
+                )
+                break
+
+            step_result = await self._act(context, decision)
+            step = Step(decision=decision, result=step_result)
+            result.steps.append(step)
+            await self._planner.reflect(observation, step)
+
+            # Stuck detection, keyed on *progress* rather than on repetition.
+            #
+            # An earlier version broke only on identical consecutive actions,
+            # and a live run walked straight past it: the commonest loop is
+            # act, look, act, look -- never two the same in a row, and never
+            # getting anywhere. Any step that changes something clears the
+            # window, so what this measures is simply "nothing has happened for
+            # N actions", whatever shape they took.
+            signature = (decision.tool, repr(sorted(decision.arguments.items())))
+            if step_result.changed:
+                recent.clear()
+            else:
+                recent.append(signature)
+                if len(recent) >= self._config.repeat_limit:
+                    tools_tried = ", ".join(sorted({name for name, _ in recent}))
+                    result.stop_reason = StopReason.STUCK
+                    result.error = (
+                        f"{len(recent)} actions with no effect on the page (tried: {tools_tried})"
+                    )
+                    break
+        else:
+            result.stop_reason = StopReason.BUDGET
+
+        result.elapsed = time.monotonic() - started
+        # Cleared at the END, not the start: a stop requested before this run
+        # began -- or between runs -- must be honoured, not discarded by the
+        # very call it was meant to stop.
+        self._stop.clear()
+        return result
+
+    # ------------------------------------------------------------------ #
+    # Internals                                                           #
+    # ------------------------------------------------------------------ #
+
+    async def _observe(
+        self, goal: str, history: Sequence[Step], notes: Sequence[str], index: int
+    ) -> Observation:
+        snapshot = await self._engine.snapshot()
+        screenshot: Screenshot | None = None
+        if self._config.include_screenshot:
+            try:
+                screenshot = await self._engine.screenshot()
+            except AnyBrowserError:
+                # A planner that can read a snapshot can work without pixels;
+                # losing the screenshot should degrade the run, not end it.
+                logger.debug("screenshot unavailable", exc_info=True)
+        return Observation(
+            goal=goal,
+            snapshot=snapshot,
+            screenshot=screenshot,
+            history=tuple(history),
+            notes=tuple(notes),
+            step_index=index,
+        )
+
+    async def _act(self, context: ToolContext, decision: Decision) -> ToolResult:
+        tool = self._by_name.get(decision.tool)
+        if tool is None:
+            known = ", ".join(sorted(self._by_name))
+            return ToolResult.failure(f"no tool named {decision.tool!r}; available: {known}")
+
+        # The harness raises the confirmation, not the agent. A prompt-level
+        # "ask before destructive actions" rule is advisory and leaks; a gate at
+        # dispatch cannot be talked out of.
+        gated = tool.mutating and self._config.confirm is not None
+        if gated and not self._config.confirm(decision):  # type: ignore[misc]
+            return ToolResult.failure("refused: the action was not confirmed")
+
+        try:
+            return await tool.run(context, **dict(decision.arguments))
+        except TypeError as exc:
+            return ToolResult.failure(f"bad arguments for {decision.tool}: {exc}")
+        except AnyBrowserError as exc:
+            return ToolResult.failure(str(exc), error_type=type(exc).__name__)
+        except Exception as exc:  # a third-party tool may raise anything
+            logger.exception("tool %s failed", decision.tool)
+            return ToolResult.failure(f"{decision.tool} raised: {exc}")
+
+
+def render_history(steps: Sequence[Step], *, limit: int = 20) -> str:
+    """Format history for a prompt.
+
+    The ``[no effect]`` marker is the whole point of this function. Without it
+    every line reads as progress and the model has no way to tell a working
+    action from one that has been failing silently for five turns.
+    """
+    lines: list[str] = []
+    for index, step in enumerate(steps[-limit:], start=max(1, len(steps) - limit + 1)):
+        marker = "" if step.result.changed else "  [no effect]"
+        if not step.result.ok:
+            marker = "  [failed]"
+        arguments = ", ".join(f"{k}={v!r}" for k, v in step.decision.arguments.items())
+        lines.append(
+            f"{index}. {step.decision.tool}({arguments}){marker}\n"
+            f"   why: {step.decision.narrative}\n"
+            f"   result: {step.result.summary}"
+        )
+    return "\n".join(lines)