sentienceapi 0.90.17__py3-none-any.whl

sentience/agent_config.py

@@ -0,0 +1,43 @@
+"""
+Configuration classes for Sentience agents.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AgentConfig:
+    """
+    Configuration for Sentience Agent execution.
+
+    This dataclass provides centralized configuration for agent behavior,
+    including snapshot limits, retry logic, verification, and screenshot capture.
+
+    Attributes:
+        snapshot_limit: Maximum elements to include in LLM context (default: 50)
+        temperature: LLM temperature 0.0-1.0 for response generation (default: 0.0)
+        max_retries: Number of retries on action failure (default: 1)
+        verify: Whether to run verification step after actions (default: True)
+        capture_screenshots: Whether to capture screenshots during execution (default: True)
+        screenshot_format: Screenshot format 'png' or 'jpeg' (default: 'jpeg')
+        screenshot_quality: JPEG quality 1-100, ignored for PNG (default: 80)
+
+    Example:
+        >>> from sentience import AgentConfig, SentienceAgent
+        >>> config = AgentConfig(
+        ...     snapshot_limit=100,
+        ...     max_retries=2,
+        ...     verify=True
+        ... )
+        >>> agent = SentienceAgent(browser, llm, config=config)
+    """
+
+    snapshot_limit: int = 50
+    temperature: float = 0.0
+    max_retries: int = 1
+    verify: bool = True
+
+    # Screenshot options
+    capture_screenshots: bool = True
+    screenshot_format: str = "jpeg"  # "png" or "jpeg"
+    screenshot_quality: int = 80  # 1-100 (for JPEG only)

sentience/async_api.py

@@ -0,0 +1,101 @@
+"""
+Async API for Sentience SDK - Convenience re-exports
+
+This module re-exports all async functions for backward compatibility and developer convenience.
+You can also import directly from their respective modules:
+
+    # Option 1: From async_api (recommended for convenience)
+    from sentience.async_api import (
+        AsyncSentienceBrowser,
+        snapshot_async,
+        click_async,
+        wait_for_async,
+        screenshot_async,
+        find_text_rect_async,
+        # ... all async functions in one place
+    )
+
+    # Option 2: From respective modules (also works)
+    from sentience.browser import AsyncSentienceBrowser
+    from sentience.snapshot import snapshot_async
+    from sentience.actions import click_async
+"""
+
+# ========== Actions (Phase 1) ==========
+# Re-export async action functions from actions.py
+from sentience.actions import click_async, click_rect_async, press_async, type_text_async
+
+# ========== Phase 2C: Agent Layer ==========
+# Re-export async agent classes from agent.py and base_agent.py
+from sentience.agent import SentienceAgentAsync
+from sentience.base_agent import BaseAgentAsync
+
+# ========== Browser ==========
+# Re-export AsyncSentienceBrowser from browser.py (moved there for better organization)
+from sentience.browser import AsyncSentienceBrowser
+
+# Re-export async expect functions from expect.py
+from sentience.expect import ExpectationAsync, expect_async
+from sentience.inspector import InspectorAsync, inspect_async
+
+# Re-export async overlay functions from overlay.py
+from sentience.overlay import clear_overlay_async, show_overlay_async
+
+# ========== Query Functions (Pure Functions - No Async Needed) ==========
+# Re-export query functions (pure functions, no async needed)
+from sentience.query import find, query
+
+# ========== Phase 2B: Supporting Utilities ==========
+# Re-export async read function from read.py
+from sentience.read import read_async
+
+# ========== Phase 2D: Developer Tools ==========
+# Re-export async recorder and inspector from their modules
+from sentience.recorder import RecorderAsync, record_async
+
+# Re-export async screenshot function from screenshot.py
+from sentience.screenshot import screenshot_async
+
+# ========== Snapshot (Phase 1) ==========
+# Re-export async snapshot functions from snapshot.py
+from sentience.snapshot import snapshot_async
+
+# Re-export async text search function from text_search.py
+from sentience.text_search import find_text_rect_async
+
+# ========== Phase 2A: Core Utilities ==========
+# Re-export async wait function from wait.py
+from sentience.wait import wait_for_async
+
+__all__ = [
+    # Browser
+    "AsyncSentienceBrowser",  # Re-exported from browser.py
+    # Snapshot (Phase 1)
+    "snapshot_async",  # Re-exported from snapshot.py
+    # Actions (Phase 1)
+    "click_async",  # Re-exported from actions.py
+    "type_text_async",  # Re-exported from actions.py
+    "press_async",  # Re-exported from actions.py
+    "click_rect_async",  # Re-exported from actions.py
+    # Phase 2A: Core Utilities
+    "wait_for_async",  # Re-exported from wait.py
+    "screenshot_async",  # Re-exported from screenshot.py
+    "find_text_rect_async",  # Re-exported from text_search.py
+    # Phase 2B: Supporting Utilities
+    "read_async",  # Re-exported from read.py
+    "show_overlay_async",  # Re-exported from overlay.py
+    "clear_overlay_async",  # Re-exported from overlay.py
+    "expect_async",  # Re-exported from expect.py
+    "ExpectationAsync",  # Re-exported from expect.py
+    # Phase 2C: Agent Layer
+    "SentienceAgentAsync",  # Re-exported from agent.py
+    "BaseAgentAsync",  # Re-exported from base_agent.py
+    # Phase 2D: Developer Tools
+    "RecorderAsync",  # Re-exported from recorder.py
+    "record_async",  # Re-exported from recorder.py
+    "InspectorAsync",  # Re-exported from inspector.py
+    "inspect_async",  # Re-exported from inspector.py
+    # Query Functions
+    "find",  # Re-exported from query.py
+    "query",  # Re-exported from query.py
+]

sentience/base_agent.py

@@ -0,0 +1,194 @@
+"""
+BaseAgent: Abstract base class for all Sentience agents
+Defines the interface that all agent implementations must follow
+"""
+
+from abc import ABC, abstractmethod
+
+from .models import ActionHistory, AgentActionResult, Element, Snapshot, TokenStats
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for all Sentience agents.
+
+    Provides a standard interface for:
+    - Executing natural language goals (act)
+    - Tracking execution history
+    - Monitoring token usage
+    - Filtering elements based on goals
+
+    Subclasses must implement:
+    - act(): Execute a natural language goal
+    - get_history(): Return execution history
+    - get_token_stats(): Return token usage statistics
+    - clear_history(): Reset history and token counters
+
+    Subclasses can override:
+    - filter_elements(): Customize element filtering logic
+    """
+
+    @abstractmethod
+    def act(self, goal: str, **kwargs) -> AgentActionResult:
+        """
+        Execute a natural language goal using the agent.
+
+        Args:
+            goal: Natural language instruction (e.g., "Click the login button")
+            **kwargs: Additional parameters (implementation-specific)
+
+        Returns:
+            AgentActionResult with execution details
+
+        Raises:
+            RuntimeError: If execution fails after retries
+        """
+        pass
+
+    @abstractmethod
+    def get_history(self) -> list[ActionHistory]:
+        """
+        Get the execution history of all actions taken.
+
+        Returns:
+            List of ActionHistory entries
+        """
+        pass
+
+    @abstractmethod
+    def get_token_stats(self) -> TokenStats:
+        """
+        Get token usage statistics for the agent session.
+
+        Returns:
+            TokenStats with cumulative token counts
+        """
+        pass
+
+    @abstractmethod
+    def clear_history(self) -> None:
+        """
+        Clear execution history and reset token counters.
+
+        This resets the agent to a clean state.
+        """
+        pass
+
+    def filter_elements(self, snapshot: Snapshot, goal: str | None = None) -> list[Element]:
+        """
+        Filter elements from a snapshot based on goal context.
+
+        Default implementation returns all elements unchanged.
+        Subclasses can override to implement custom filtering logic
+        such as:
+        - Removing irrelevant elements based on goal keywords
+        - Boosting importance of matching elements
+        - Filtering by role, size, or visual properties
+
+        Args:
+            snapshot: Current page snapshot
+            goal: User's goal (can inform filtering strategy)
+
+        Returns:
+            Filtered list of elements (default: all elements)
+
+        Example:
+            >>> agent = SentienceAgent(browser, llm)
+            >>> snap = snapshot(browser)
+            >>> filtered = agent.filter_elements(snap, goal="Click login")
+            >>> # filtered now contains only relevant elements
+        """
+        return snapshot.elements
+
+
+class BaseAgentAsync(ABC):
+    """
+    Abstract base class for all async Sentience agents.
+
+    Provides a standard interface for:
+    - Executing natural language goals (act)
+    - Tracking execution history
+    - Monitoring token usage
+    - Filtering elements based on goals
+
+    Subclasses must implement:
+    - act(): Execute a natural language goal (async)
+    - get_history(): Return execution history
+    - get_token_stats(): Return token usage statistics
+    - clear_history(): Reset history and token counters
+
+    Subclasses can override:
+    - filter_elements(): Customize element filtering logic
+    """
+
+    @abstractmethod
+    async def act(self, goal: str, **kwargs) -> AgentActionResult:
+        """
+        Execute a natural language goal using the agent (async).
+
+        Args:
+            goal: Natural language instruction (e.g., "Click the login button")
+            **kwargs: Additional parameters (implementation-specific)
+
+        Returns:
+            AgentActionResult with execution details
+
+        Raises:
+            RuntimeError: If execution fails after retries
+        """
+        pass
+
+    @abstractmethod
+    def get_history(self) -> list[ActionHistory]:
+        """
+        Get the execution history of all actions taken.
+
+        Returns:
+            List of ActionHistory entries
+        """
+        pass
+
+    @abstractmethod
+    def get_token_stats(self) -> TokenStats:
+        """
+        Get token usage statistics for the agent session.
+
+        Returns:
+            TokenStats with cumulative token counts
+        """
+        pass
+
+    @abstractmethod
+    def clear_history(self) -> None:
+        """
+        Clear execution history and reset token counters.
+
+        This resets the agent to a clean state.
+        """
+        pass
+
+    def filter_elements(self, snapshot: Snapshot, goal: str | None = None) -> list[Element]:
+        """
+        Filter elements from a snapshot based on goal context.
+
+        Default implementation returns all elements unchanged.
+        Subclasses can override to implement custom filtering logic
+        such as:
+        - Removing irrelevant elements based on goal keywords
+        - Boosting importance of matching elements
+        - Filtering by role, size, or visual properties
+
+        Args:
+            snapshot: Current page snapshot
+            goal: User's goal (can inform filtering strategy)
+
+        Returns:
+            Filtered list of elements (default: all elements)
+
+        Example:
+            >>> agent = SentienceAgentAsync(browser, llm)
+            >>> snap = await snapshot_async(browser)
+            >>> filtered = agent.filter_elements(snap, goal="Click login")
+            >>> # filtered now contains only relevant elements
+        """
+        return snapshot.elements