notte-sdk 0.0.dev0__py3-none-any.whl

notte_sdk/endpoints/base.py

@@ -0,0 +1,247 @@
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Any, ClassVar, Generic, Literal, Self, TypeVar
+
+import requests
+from loguru import logger
+from pydantic import BaseModel
+
+from notte_sdk.errors import AuthenticationError, NotteAPIError
+
+TResponse = TypeVar("TResponse", bound=BaseModel, covariant=True)
+
+
+class NotteEndpoint(BaseModel, Generic[TResponse]):
+    path: str
+    response: type[TResponse]
+    request: BaseModel | None = None
+    method: Literal["GET", "POST", "DELETE"]
+    params: BaseModel | None = None
+
+    def with_request(self, request: BaseModel) -> Self:
+        # return deep copy of self with the request set
+        """
+        Return a deep copy of the endpoint with the specified request.
+
+        Creates a new instance of the endpoint with its request attribute updated to the provided model.
+        The original instance remains unmodified.
+
+        Args:
+            request: A Pydantic model instance carrying the request data.
+
+        Returns:
+            A new endpoint instance with the updated request.
+        """
+        return self.model_copy(update={"request": request})
+
+    def with_params(self, params: BaseModel) -> Self:
+        # return deep copy of self with the params set
+        """
+        Return a new endpoint instance with updated parameters.
+
+        Creates a copy of the current endpoint with its "params" attribute set to the provided
+        Pydantic model.
+
+        Args:
+            params: A Pydantic model instance containing the new parameters.
+        """
+        return self.model_copy(update={"params": params})
+
+
+class BaseClient(ABC):
+    DEFAULT_NOTTE_API_URL: ClassVar[str] = "https://api.notte.cc"
+    DEFAULT_REQUEST_TIMEOUT_SECONDS: ClassVar[int] = 60
+
+    def __init__(
+        self,
+        base_endpoint_path: str | None,
+        api_key: str | None = None,
+        verbose: bool = False,
+    ):
+        """
+        Initialize a new API client instance.
+
+        Sets up the client by resolving an API key from the provided parameter or the
+        NOTTE_API_KEY environment variable. Selects the server URL (defaulting to a
+        preconfigured server if none is provided), initializes a mapping of endpoints
+        using the implemented 'endpoints' method, and stores an optional base endpoint
+        path for constructing request URLs.
+
+        Args:
+            base_endpoint_path: Optional base path to be prefixed to endpoint URLs.
+            api_key: Optional API key for authentication; if not supplied, retrieved from
+                the NOTTE_API_KEY environment variable.
+
+        Raises:
+            AuthenticationError: If an API key is neither provided nor available in the environment.
+        """
+        token = api_key or os.getenv("NOTTE_API_KEY")
+        if token is None:
+            raise AuthenticationError("NOTTE_API_KEY needs to be provided")
+        self.token: str = token
+        if os.getenv("NOTTE_API_URL") is not None and os.getenv("NOTTE_API_URL") != self.DEFAULT_NOTTE_API_URL:
+            logger.warning(f"Custom NOTTE_API_URL is set: {os.getenv('NOTTE_API_URL')}")
+        self.server_url: str = os.getenv("NOTTE_API_URL") or self.DEFAULT_NOTTE_API_URL
+        self._endpoints: dict[str, NotteEndpoint[BaseModel]] = {
+            endpoint.path: endpoint for endpoint in self.endpoints()
+        }
+        self.base_endpoint_path: str | None = base_endpoint_path
+        self.verbose: bool = verbose
+
+    @staticmethod
+    @abstractmethod
+    def endpoints() -> Sequence[NotteEndpoint[BaseModel]]:
+        """
+        Return API endpoints for the client.
+
+        This abstract method should be implemented by subclasses to supply the list of available
+        NotteEndpoint instances for the client.
+
+        Returns:
+            Sequence[NotteEndpoint[BaseModel]]: A list of endpoints for the client.
+        """
+        pass
+
+    def headers(self) -> dict[str, str]:
+        """
+        Return HTTP headers for authenticated API requests.
+
+        Constructs and returns a dictionary containing the 'Authorization' header,
+        which is formatted as a Bearer token using the API key stored in self.token.
+        """
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def request_path(self, endpoint: NotteEndpoint[TResponse]) -> str:
+        """
+        Constructs the full request URL for the given API endpoint.
+
+        If a base endpoint path is defined, the URL is formed by concatenating the server URL,
+        the base endpoint path, and the endpoint's path. Otherwise, the endpoint's path is appended
+        directly to the server URL.
+        """
+        if self.base_endpoint_path is None:
+            return f"{self.server_url}/{endpoint.path}"
+        return f"{self.server_url}/{self.base_endpoint_path}/{endpoint.path}"
+
+    def _request(self, endpoint: NotteEndpoint[TResponse]) -> requests.Response:
+        """
+        Executes an HTTP request for the given API endpoint.
+
+        Constructs the full URL and headers from the endpoint's configuration and issues an HTTP
+        request using the specified method (GET, POST, or DELETE). For POST requests, a request model
+        must be provided; otherwise, a ValueError is raised. If the response status code is not 200 or
+        the JSON response contains an error detail, a NotteAPIError is raised.
+
+        Args:
+            endpoint: An API endpoint instance containing the HTTP method, path, optional request model,
+                and query parameters.
+
+        Returns:
+            The JSON-decoded response from the API.
+
+        Raises:
+            ValueError: If a POST request is attempted without a request model.
+            NotteAPIError: If the API response indicates a failure.
+        """
+        headers = self.headers()
+        url = self.request_path(endpoint)
+        params = endpoint.params.model_dump() if endpoint.params is not None else None
+        if self.verbose:
+            logger.info(f"Making `{endpoint.method}` request to `{endpoint.path} (i.e `{url}`) with params `{params}`.")
+        match endpoint.method:
+            case "GET":
+                response = requests.get(
+                    url=url,
+                    headers=headers,
+                    params=params,
+                    timeout=self.DEFAULT_REQUEST_TIMEOUT_SECONDS,
+                )
+            case "POST":
+                if endpoint.request is None:
+                    raise ValueError("Request model is required for POST requests")
+                response = requests.post(
+                    url=url,
+                    headers=headers,
+                    json=endpoint.request.model_dump(),
+                    params=params,
+                    timeout=self.DEFAULT_REQUEST_TIMEOUT_SECONDS,
+                )
+            case "DELETE":
+                response = requests.delete(
+                    url=url,
+                    headers=headers,
+                    params=params,
+                    timeout=self.DEFAULT_REQUEST_TIMEOUT_SECONDS,
+                )
+        if response.status_code != 200:
+            raise NotteAPIError(path=f"{self.base_endpoint_path}/{endpoint.path}", response=response)
+        response_dict: Any = response.json()
+        if "detail" in response_dict:
+            raise NotteAPIError(path=f"{self.base_endpoint_path}/{endpoint.path}", response=response)
+        return response_dict
+
+    def request(self, endpoint: NotteEndpoint[TResponse]) -> TResponse:
+        """
+        Requests the specified API endpoint and returns the validated response.
+
+        This method sends an HTTP request according to the endpoint configuration and
+        validates that the response is a dictionary. It then parses the response using the
+        endpoint's associated response model. If the response is not a dictionary, a
+        NotteAPIError is raised.
+
+        Args:
+            endpoint: The API endpoint configuration containing request details and the
+                      expected response model.
+
+        Returns:
+            The validated response parsed using the endpoint's response model.
+
+        Raises:
+            NotteAPIError: If the API response is not a dictionary.
+        """
+        response: Any = self._request(endpoint)
+        if not isinstance(response, dict):
+            raise NotteAPIError(path=f"{self.base_endpoint_path}/{endpoint.path}", response=response)
+        return endpoint.response.model_validate(response)
+
+    def request_list(self, endpoint: NotteEndpoint[TResponse]) -> Sequence[TResponse]:
+        # Handle the case where TResponse is a list of BaseModel
+        """
+        Retrieves and validates a list of responses from the API.
+
+        This method sends a request using the provided endpoint and expects the response to be a list. Each item is validated
+        against the model defined in the endpoint. A NotteAPIError is raised if the response is not a list.
+
+        Parameters:
+            endpoint: The API endpoint containing the path and the expected response model.
+
+        Returns:
+            A list of validated response items.
+
+        Raises:
+            NotteAPIError: If the response is not a list.
+        """
+        response_list: Any = self._request(endpoint)
+        if not isinstance(response_list, list):
+            raise NotteAPIError(path=f"{self.base_endpoint_path}/{endpoint.path}", response=response_list)
+        return [endpoint.response.model_validate(item) for item in response_list]  # pyright: ignore[reportUnknownVariableType]
+
+    def _request_file(
+        self, endpoint: NotteEndpoint[TResponse], file_type: str, output_file: str | None = None
+    ) -> bytes:
+        url = self.request_path(endpoint)
+        response = requests.get(
+            url=url,
+            headers=self.headers(),
+            timeout=self.DEFAULT_REQUEST_TIMEOUT_SECONDS,
+        )
+        if b"not found" in response.content:
+            raise ValueError("Replay is not available.")
+
+        if output_file is not None:
+            if not output_file.endswith(f".{file_type}"):
+                raise ValueError(f"Output file must have a .{file_type} extension.")
+            with open(output_file, "wb") as f:
+                _ = f.write(response.content)
+        return response.content

notte_sdk/endpoints/page.py

@@ -0,0 +1,215 @@
+from collections.abc import Sequence
+from typing import TypeVar, Unpack
+
+from notte_core.actions.space import ActionSpace
+from notte_core.browser.observation import Observation
+from notte_core.controller.space import SpaceCategory
+from notte_core.data.space import DataSpace
+from pydantic import BaseModel
+from typing_extensions import final, override
+
+from notte_sdk.endpoints.base import BaseClient, NotteEndpoint
+from notte_sdk.types import (
+    ObserveRequest,
+    ObserveRequestDict,
+    ObserveResponse,
+    ScrapeRequest,
+    ScrapeRequestDict,
+    ScrapeResponse,
+    SessionRequest,
+    StepRequest,
+    StepRequestDict,
+)
+
+TSessionRequestDict = TypeVar("TSessionRequestDict", bound=SessionRequest)
+
+
+@final
+class PageClient(BaseClient):
+    """
+    Client for the Notte API.
+
+    Note: this client is only able to handle one session at a time.
+    If you need to handle multiple sessions, you need to create a new client for each session.
+    """
+
+    # Session
+    PAGE_SCRAPE = "{session_id}/page/scrape"
+    PAGE_OBSERVE = "{session_id}/page/observe"
+    PAGE_STEP = "{session_id}/page/step"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        verbose: bool = False,
+    ):
+        """
+        Initialize the PageClient instance.
+
+        Configures the client with the page base endpoint for interacting with the Notte API and initializes session tracking for subsequent requests.
+
+        Args:
+            api_key: Optional API key used for authenticating API requests.
+        """
+        # TODO: change to page base endpoint when it's deployed
+        super().__init__(base_endpoint_path="sessions", api_key=api_key, verbose=verbose)
+
+    @staticmethod
+    def page_scrape_endpoint(session_id: str | None = None) -> NotteEndpoint[ScrapeResponse]:
+        """
+        Creates a NotteEndpoint for the scrape action.
+
+        Returns:
+            NotteEndpoint[ObserveResponse]: An endpoint configured with the scrape path,
+            POST method, and an expected ObserveResponse.
+        """
+        path = PageClient.PAGE_SCRAPE
+        if session_id is not None:
+            path = path.format(session_id=session_id)
+        return NotteEndpoint(path=path, response=ScrapeResponse, method="POST")
+
+    @staticmethod
+    def page_observe_endpoint(session_id: str | None = None) -> NotteEndpoint[ObserveResponse]:
+        """
+        Creates a NotteEndpoint for observe operations.
+
+        Returns:
+            NotteEndpoint[ObserveResponse]: An endpoint configured with the observe path,
+            using the HTTP POST method and expecting an ObserveResponse.
+        """
+        path = PageClient.PAGE_OBSERVE
+        if session_id is not None:
+            path = path.format(session_id=session_id)
+        return NotteEndpoint(path=path, response=ObserveResponse, method="POST")
+
+    @staticmethod
+    def page_step_endpoint(session_id: str | None = None) -> NotteEndpoint[ObserveResponse]:
+        """
+        Creates a NotteEndpoint for initiating a step action.
+
+        Returns a NotteEndpoint configured with the 'POST' method using the PAGE_STEP path and expecting an ObserveResponse.
+        """
+        path = PageClient.PAGE_STEP
+        if session_id is not None:
+            path = path.format(session_id=session_id)
+        return NotteEndpoint(path=path, response=ObserveResponse, method="POST")
+
+    @override
+    @staticmethod
+    def endpoints() -> Sequence[NotteEndpoint[BaseModel]]:
+        """
+        Returns the API endpoints for scraping, observing, and stepping actions.
+
+        This function aggregates and returns the endpoints used by the client to perform
+        scrape, observe, and step operations with the Notte API.
+        """
+        return [
+            PageClient.page_scrape_endpoint(),
+            PageClient.page_observe_endpoint(),
+            PageClient.page_step_endpoint(),
+        ]
+
+    def scrape(self, session_id: str, **data: Unpack[ScrapeRequestDict]) -> DataSpace:
+        """
+        Scrapes a page using provided parameters via the Notte API.
+
+        Validates the scraped request data to ensure that either a URL or session ID is provided.
+        If both are omitted, raises an InvalidRequestError. The request is sent to the configured
+        scrape endpoint and the resulting response is formatted into an Observation object.
+
+        Args:
+            **data: Arbitrary keyword arguments validated against ScrapeRequestDict,
+                   expecting at least one of 'url' or 'session_id'.
+
+        Returns:
+            An Observation object containing metadata, screenshot, action space, and data space.
+
+        Raises:
+            InvalidRequestError: If neither 'url' nor 'session_id' is supplied.
+        """
+        request = ScrapeRequest.model_validate(data)
+        endpoint = PageClient.page_scrape_endpoint(session_id=session_id)
+        response = self.request(endpoint.with_request(request))
+        # Manually override the data.structured space to better match the response format
+        response_format = request.response_format
+        structured = response.data.structured
+        if response_format is not None and structured is not None:
+            if structured.success and structured.data is not None:
+                structured.data = response_format.model_validate(structured.data.model_dump())
+        return response.data
+
+    def observe(self, session_id: str, **data: Unpack[ObserveRequestDict]) -> Observation:
+        """
+        Observes a page via the Notte API.
+
+        Constructs and validates an observation request from the provided keyword arguments.
+        Either a 'url' or a 'session_id' must be supplied; otherwise, an InvalidRequestError is raised.
+        The request is sent to the observe endpoint, and the response is formatted into an Observation object.
+
+        Parameters:
+            **data: Arbitrary keyword arguments corresponding to observation request fields.
+                    At least one of 'url' or 'session_id' must be provided.
+
+        Returns:
+            Observation: The formatted observation result from the API response.
+        """
+        request = ObserveRequest.model_validate(data)
+        endpoint = PageClient.page_observe_endpoint(session_id=session_id)
+        obs_response = self.request(endpoint.with_request(request))
+        return self._format_observe_response(obs_response)
+
+    def step(self, session_id: str, **data: Unpack[StepRequestDict]) -> Observation:
+        """
+        Sends a step action request and returns an Observation.
+
+        Validates the provided keyword arguments to ensure they conform to the step
+        request schema, retrieves the step endpoint, submits the request, and transforms
+        the API response into an Observation.
+
+        Args:
+            **data: Arbitrary keyword arguments matching the expected structure for a
+                step request.
+
+        Returns:
+            An Observation object constructed from the API response.
+        """
+        request = StepRequest.model_validate(data)
+        endpoint = PageClient.page_step_endpoint(session_id=session_id)
+        obs_response = self.request(endpoint.with_request(request))
+        return self._format_observe_response(obs_response)
+
+    def _format_observe_response(self, response: ObserveResponse) -> Observation:
+        """
+        Formats an observe response into an Observation object.
+
+        Extracts session information from the provided response to update the client's last session state
+        and constructs an Observation using response metadata and screenshot. If the response does not include
+        space or data details, those Observation attributes are set to None; otherwise, they are converted into
+        an ActionSpace or DataSpace instance respectively.
+
+        Args:
+            response: An ObserveResponse object containing session, metadata, screenshot, space, and data.
+
+        Returns:
+            An Observation object representing the formatted response.
+        """
+        return Observation(
+            metadata=response.metadata,
+            screenshot=response.screenshot,
+            space=(
+                ActionSpace(
+                    description=response.space.description,
+                    raw_actions=response.space.actions,
+                    category=None if response.space.category is None else SpaceCategory(response.space.category),
+                )
+            ),
+            data=(
+                None
+                if response.data is None
+                else DataSpace(
+                    markdown=response.data.markdown,
+                    images=(None if response.data.images is None else response.data.images),
+                    structured=None if response.data.structured is None else response.data.structured,
+                )
+            ),
+        )