browser-handoff 0.1.0__py3-none-any.whl

browser_handoff/__init__.py

@@ -0,0 +1,46 @@
+"""browser-handoff — Human-in-the-loop fallback for browser automation.
+
+A standalone library that pauses your Playwright automation, hands the
+page off to a human via CDP-based streaming, and resumes when they're
+done — for OAuth, 2FA, payments, identity checks, or any flow that
+requires a human.
+
+Example:
+    from browser_handoff import Handoff, Scenario
+    from browser_handoff.detection import Detection
+
+    handoff = Handoff(
+        scenarios=[
+            Scenario(
+                name="login_required",
+                trigger=Detection.element(present=['input[type="email"]']),
+                complete=Detection.url(path_contains=["/dashboard"]),
+            ),
+        ],
+    )
+
+    result = await handoff.run(page)
+    if result.was_blocked and not result.timed_out:
+        print(f"Human completed: {result.scenario_name}")
+    await bot_logic(page)
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .handoff import Handoff, HandoffResult
+from .scenario import Scenario
+from .server import ServerConfig
+
+try:
+    __version__ = version("browser-handoff")
+except PackageNotFoundError:
+    # Package is not installed (e.g. running from a checkout without `pip install -e .`).
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "Handoff",
+    "HandoffResult",
+    "Scenario",
+    "ServerConfig",
+    "__version__",
+]

browser_handoff/config/__init__.py

@@ -0,0 +1,10 @@
+"""Configuration loading and validation for browser-handoff."""
+
+from .loader import interpolate_env_vars, load_file, load_json, load_yaml
+
+__all__ = [
+    "interpolate_env_vars",
+    "load_file",
+    "load_json",
+    "load_yaml",
+]

browser_handoff/config/loader.py

@@ -0,0 +1,102 @@
+"""Configuration loading with JSON/YAML support and env var interpolation."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+
+def interpolate_env_vars(config: Any) -> Any:
+    """Recursively interpolate ${VAR} patterns with environment variables.
+
+    Args:
+        config: Configuration dict, list, or value to interpolate.
+
+    Returns:
+        The interpolated configuration.
+
+    Example:
+        config = {"url": "${BASE_URL}/api"}
+        result = interpolate_env_vars(config)
+        # If BASE_URL=https://example.com, result is {"url": "https://example.com/api"}
+    """
+    pattern = re.compile(r"\$\{([^}]+)\}")
+
+    def replace(value: Any) -> Any:
+        if isinstance(value, str):
+            return pattern.sub(
+                lambda m: os.environ.get(m.group(1), m.group(0)), value
+            )
+        elif isinstance(value, dict):
+            return {k: replace(v) for k, v in value.items()}
+        elif isinstance(value, list):
+            return [replace(v) for v in value]
+        return value
+
+    return replace(config)
+
+
+def load_json(content: str) -> dict[str, Any]:
+    """Load configuration from JSON string.
+
+    Args:
+        content: JSON string content.
+
+    Returns:
+        Parsed and interpolated configuration dict.
+    """
+    config = json.loads(content)
+    return interpolate_env_vars(config)
+
+
+def load_yaml(content: str) -> dict[str, Any]:
+    """Load configuration from YAML string.
+
+    Args:
+        content: YAML string content.
+
+    Returns:
+        Parsed and interpolated configuration dict.
+
+    Raises:
+        ImportError: If PyYAML is not installed.
+    """
+    import yaml
+
+    config = yaml.safe_load(content)
+    return interpolate_env_vars(config)
+
+
+def load_file(path: str | Path) -> dict[str, Any]:
+    """Load configuration from a JSON or YAML file.
+
+    Args:
+        path: Path to the configuration file.
+
+    Returns:
+        Parsed and interpolated configuration dict.
+
+    Raises:
+        ValueError: If file extension is not .json, .yaml, or .yml.
+        FileNotFoundError: If file does not exist.
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {path}")
+
+    content = path.read_text(encoding="utf-8")
+    suffix = path.suffix.lower()
+
+    if suffix == ".json":
+        return load_json(content)
+    elif suffix in (".yaml", ".yml"):
+        return load_yaml(content)
+    else:
+        raise ValueError(
+            f"Unsupported configuration file format: {suffix}. "
+            "Use .json, .yaml, or .yml"
+        )

browser_handoff/detection/__init__.py

@@ -0,0 +1,172 @@
+"""Detection types and factory for browser-handoff."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import BaseDetection, DetectionResult
+from .combinators import AllDetection, AnyDetection, NotDetection
+from .content import ContentDetection
+from .element import ElementDetection
+from .url import UrlDetection
+
+# LLM detection is optional
+try:
+    from .llm import LLMDetection
+
+    _HAS_LLM = True
+except ImportError:
+    _HAS_LLM = False
+    LLMDetection = None  # type: ignore
+
+
+class Detection:
+    """Factory class for creating detection instances.
+
+    Example:
+        # Content detection
+        detection = Detection.content(
+            title_contains=["Sign In"],
+            body_contains=["please log in"],
+        )
+
+        # URL detection
+        detection = Detection.url(
+            host_equals=["localhost"],
+            path_matches=["/callback"],
+        )
+
+        # Combinators
+        detection = Detection.all([
+            Detection.element(present=["#dashboard"]),
+            Detection.not_(Detection.element(present=[".error"])),
+        ])
+    """
+
+    @staticmethod
+    def content(
+        title_contains: list[str] | None = None,
+        title_matches: list[str] | None = None,
+        body_contains: list[str] | None = None,
+        body_matches: list[str] | None = None,
+    ) -> ContentDetection:
+        """Create a content-based detection."""
+        return ContentDetection(
+            title_contains=title_contains or [],
+            title_matches=title_matches or [],
+            body_contains=body_contains or [],
+            body_matches=body_matches or [],
+        )
+
+    @staticmethod
+    def url(
+        scheme_equals: str | None = None,
+        host_equals: list[str] | None = None,
+        host_not_equals: list[str] | None = None,
+        path_matches: list[str] | None = None,
+        path_contains: list[str] | None = None,
+        query_contains: list[str] | None = None,
+    ) -> UrlDetection:
+        """Create a URL-based detection."""
+        return UrlDetection(
+            scheme_equals=scheme_equals,
+            host_equals=host_equals or [],
+            host_not_equals=host_not_equals or [],
+            path_matches=path_matches or [],
+            path_contains=path_contains or [],
+            query_contains=query_contains or [],
+        )
+
+    @staticmethod
+    def element(
+        present: list[str] | None = None,
+        missing: list[str] | None = None,
+        visible: list[str] | None = None,
+        hidden: list[str] | None = None,
+    ) -> ElementDetection:
+        """Create an element-based detection."""
+        return ElementDetection(
+            present=present or [],
+            missing=missing or [],
+            visible=visible or [],
+            hidden=hidden or [],
+        )
+
+    @staticmethod
+    def llm(
+        model: str = "anthropic/claude-sonnet-4-5",
+        condition: str = "",
+        api_key: str | None = None,
+    ) -> "LLMDetection":
+        """Create an LLM-based detection.
+
+        Requires the 'llm' extra: pip install browser-handoff[llm]
+
+        If `api_key` is None, litellm picks up the key from the provider's
+        env var (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...).
+        """
+        if not _HAS_LLM:
+            raise ImportError(
+                "LLM detection requires 'litellm' package. "
+                "Install with: pip install browser-handoff[llm]"
+            )
+        return LLMDetection(model=model, condition=condition, api_key=api_key)
+
+    @staticmethod
+    def all(conditions: list[BaseDetection]) -> AllDetection:
+        """Create an AND combinator (all conditions must match)."""
+        return AllDetection(conditions=conditions)
+
+    @staticmethod
+    def any(conditions: list[BaseDetection]) -> AnyDetection:
+        """Create an OR combinator (any condition must match)."""
+        return AnyDetection(conditions=conditions)
+
+    @staticmethod
+    def not_(condition: BaseDetection) -> NotDetection:
+        """Create a NOT combinator (invert condition)."""
+        return NotDetection(condition=condition)
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> BaseDetection:
+        """Create a detection from dictionary representation.
+
+        Args:
+            data: Dictionary with 'type' key and type-specific fields.
+
+        Returns:
+            The appropriate detection instance.
+
+        Raises:
+            ValueError: If the detection type is unknown.
+        """
+        detection_type = data.get("type")
+
+        if detection_type == "content":
+            return ContentDetection.from_dict(data)
+        elif detection_type == "url":
+            return UrlDetection.from_dict(data)
+        elif detection_type == "element":
+            return ElementDetection.from_dict(data)
+        elif detection_type == "llm":
+            if not _HAS_LLM:
+                raise ImportError(
+                    "LLM detection requires 'litellm' package. "
+                    "Install with: pip install browser-handoff[llm]"
+                )
+            return LLMDetection.from_dict(data)
+        elif detection_type == "all":
+            conditions = [Detection.from_dict(c) for c in data.get("conditions", [])]
+            return AllDetection(conditions=conditions)
+        elif detection_type == "any":
+            conditions = [Detection.from_dict(c) for c in data.get("conditions", [])]
+            return AnyDetection(conditions=conditions)
+        elif detection_type == "not":
+            condition_data = data.get("condition")
+            condition = Detection.from_dict(condition_data) if condition_data else None
+            return NotDetection(condition=condition)
+        else:
+            raise ValueError(f"Unknown detection type: {detection_type}")
+
+
+__all__ = ["Detection", "DetectionResult"]

browser_handoff/detection/base.py

@@ -0,0 +1,70 @@
+"""Base detection classes and result types."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Coroutine
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page
+
+
+@dataclass
+class DetectionResult:
+    """Result of a detection check."""
+
+    matched: bool
+    detection_type: str
+    reason: str = ""
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def __bool__(self) -> bool:
+        return self.matched
+
+
+class BaseDetection(ABC):
+    """Abstract base class for all detection types."""
+
+    detection_type: str = "base"
+
+    @abstractmethod
+    def register_listeners(
+        self,
+        page: "Page",
+        callback: Callable[["BaseDetection"], Coroutine[Any, Any, None]],
+    ) -> Callable[[], None]:
+        """Register event listeners that call callback when detection should be checked.
+
+        Args:
+            page: The Playwright page to monitor.
+            callback: Async callback to invoke when detection should be checked.
+
+        Returns:
+            A cleanup function that removes the registered listeners.
+        """
+        pass
+
+    @abstractmethod
+    async def check(self, page: "Page") -> DetectionResult:
+        """Check if detection condition is met.
+
+        Args:
+            page: The Playwright page to check.
+
+        Returns:
+            DetectionResult indicating whether condition was matched.
+        """
+        pass
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize detection to dictionary format."""
+        return {"type": self.detection_type}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "BaseDetection":
+        """Deserialize detection from dictionary format.
+
+        This should be overridden by subclasses.
+        """
+        raise NotImplementedError("Subclasses must implement from_dict")

browser_handoff/detection/combinators.py

@@ -0,0 +1,193 @@
+"""Combinator detection types (all, any, not)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Coroutine
+
+from .base import BaseDetection, DetectionResult
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page
+
+
+@dataclass
+class AllDetection(BaseDetection):
+    """AND logic - all conditions must match.
+
+    Example:
+        detection = AllDetection(conditions=[
+            UrlDetection(path_matches=["/dashboard"]),
+            ElementDetection(present=[".user-avatar"]),
+        ])
+    """
+
+    detection_type: str = field(default="all", init=False)
+    conditions: list[BaseDetection] = field(default_factory=list)
+
+    def register_listeners(
+        self,
+        page: "Page",
+        callback: Callable[["BaseDetection"], Coroutine[Any, Any, None]],
+    ) -> Callable[[], None]:
+        """Register listeners for all child conditions."""
+        cleanups: list[Callable[[], None]] = []
+
+        for condition in self.conditions:
+            cleanup = condition.register_listeners(page, callback)
+            cleanups.append(cleanup)
+
+        def cleanup_all() -> None:
+            for cleanup in cleanups:
+                try:
+                    cleanup()
+                except Exception:
+                    pass
+
+        return cleanup_all
+
+    async def check(self, page: "Page") -> DetectionResult:
+        """Check if ALL conditions are met."""
+        for condition in self.conditions:
+            result = await condition.check(page)
+            if not result.matched:
+                return DetectionResult(
+                    matched=False,
+                    detection_type=self.detection_type,
+                    reason=f"Condition '{condition.detection_type}' not met: {result.reason}",
+                    details={"failed_condition": condition.to_dict()},
+                )
+
+        return DetectionResult(
+            matched=True,
+            detection_type=self.detection_type,
+            reason="All conditions met",
+            details={"conditions_count": len(self.conditions)},
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "type": self.detection_type,
+            "conditions": [c.to_dict() for c in self.conditions],
+        }
+
+
+@dataclass
+class AnyDetection(BaseDetection):
+    """OR logic - any condition must match.
+
+    Example:
+        detection = AnyDetection(conditions=[
+            ElementDetection(present=["#success"]),
+            ContentDetection(body_contains=["Welcome"]),
+        ])
+    """
+
+    detection_type: str = field(default="any", init=False)
+    conditions: list[BaseDetection] = field(default_factory=list)
+
+    def register_listeners(
+        self,
+        page: "Page",
+        callback: Callable[["BaseDetection"], Coroutine[Any, Any, None]],
+    ) -> Callable[[], None]:
+        """Register listeners for all child conditions."""
+        cleanups: list[Callable[[], None]] = []
+
+        for condition in self.conditions:
+            cleanup = condition.register_listeners(page, callback)
+            cleanups.append(cleanup)
+
+        def cleanup_all() -> None:
+            for cleanup in cleanups:
+                try:
+                    cleanup()
+                except Exception:
+                    pass
+
+        return cleanup_all
+
+    async def check(self, page: "Page") -> DetectionResult:
+        """Check if ANY condition is met."""
+        for condition in self.conditions:
+            result = await condition.check(page)
+            if result.matched:
+                return DetectionResult(
+                    matched=True,
+                    detection_type=self.detection_type,
+                    reason=f"Condition '{condition.detection_type}' matched: {result.reason}",
+                    details={"matched_condition": condition.to_dict()},
+                )
+
+        return DetectionResult(
+            matched=False,
+            detection_type=self.detection_type,
+            reason="No conditions matched",
+            details={"conditions_count": len(self.conditions)},
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "type": self.detection_type,
+            "conditions": [c.to_dict() for c in self.conditions],
+        }
+
+
+@dataclass
+class NotDetection(BaseDetection):
+    """Invert result of a condition.
+
+    Example:
+        detection = NotDetection(
+            condition=ElementDetection(present=[".error-message"])
+        )
+    """
+
+    detection_type: str = field(default="not", init=False)
+    condition: BaseDetection | None = None
+
+    def register_listeners(
+        self,
+        page: "Page",
+        callback: Callable[["BaseDetection"], Coroutine[Any, Any, None]],
+    ) -> Callable[[], None]:
+        """Register listeners for the wrapped condition."""
+        if self.condition is None:
+            return lambda: None
+
+        return self.condition.register_listeners(page, callback)
+
+    async def check(self, page: "Page") -> DetectionResult:
+        """Check if condition is NOT met."""
+        if self.condition is None:
+            return DetectionResult(
+                matched=True,
+                detection_type=self.detection_type,
+                reason="No condition to negate",
+            )
+
+        result = await self.condition.check(page)
+
+        if result.matched:
+            return DetectionResult(
+                matched=False,
+                detection_type=self.detection_type,
+                reason=f"Condition matched (should not): {result.reason}",
+                details={"negated_condition": self.condition.to_dict()},
+            )
+        else:
+            return DetectionResult(
+                matched=True,
+                detection_type=self.detection_type,
+                reason=f"Condition not matched (as expected): {result.reason}",
+                details={"negated_condition": self.condition.to_dict()},
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "type": self.detection_type,
+            "condition": self.condition.to_dict() if self.condition else None,
+        }