notte-sdk 1.4.0__tar.gz

notte_sdk-1.4.0/.gitignore

@@ -0,0 +1,179 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+ignore.*
+llm_usage.jsonl
+llm_parsing_error.jsonl
+traces/
+
+**/__pycache__/**
+.DS_Store
+**/.DS_Store
+old
+notebook

notte_sdk-1.4.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: notte-sdk
+Version: 1.4.0
+Summary: The SDK for Notte
+Author-email: Notte Team  <hello@notte.cc>
+Requires-Python: >=3.11
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: notte-core>=1.3.3
+Requires-Dist: pydantic>=2.11.3
+Requires-Dist: requests>=2.32.3

notte_sdk-1.4.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "notte-sdk"
+version = "1.4.0"
+description = "The SDK for Notte"
+readme = "README.md"
+authors = [
+    { name = "Notte Team ", email = "hello@notte.cc" }
+]
+packages = [
+  { include = "notte_sdk", from = "src" },
+]
+
+requires-python = ">=3.11"
+dependencies = [
+    "loguru>=0.7.3",
+    "pydantic>=2.11.3",
+    "requests>=2.32.3",
+    "notte-core>=1.3.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

notte_sdk-1.4.0/src/notte_sdk/__init__.py

@@ -0,0 +1,7 @@
+from notte_core import check_notte_version
+
+from notte_sdk.client import NotteClient
+
+__version__ = check_notte_version("notte_sdk")
+
+__all__ = ["NotteClient"]

notte_sdk-1.4.0/src/notte_sdk/client.py

@@ -0,0 +1,36 @@
+from typing_extensions import final
+
+from notte_sdk.endpoints.agents import AgentsClient
+from notte_sdk.endpoints.env import EnvClient
+from notte_sdk.endpoints.persona import PersonaClient
+from notte_sdk.endpoints.sessions import SessionsClient
+from notte_sdk.endpoints.vault import VaultClient
+
+
+@final
+class NotteClient:
+    """
+    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.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        verbose: bool = False,
+    ):
+        """Initialize a NotteClient instance.
+
+        Initializes the NotteClient with the specified API key and server URL, creating instances
+        of SessionsClient, AgentsClient, and EnvClient.
+
+        Args:
+            api_key: Optional API key for authentication.
+        """
+        self.sessions: SessionsClient = SessionsClient(api_key=api_key, verbose=verbose)
+        self.agents: AgentsClient = AgentsClient(api_key=api_key, verbose=verbose)
+        self.env: EnvClient = EnvClient(api_key=api_key, verbose=verbose)
+        self.persona: PersonaClient = PersonaClient(api_key=api_key, verbose=verbose)
+        self.vault: VaultClient = VaultClient(api_key=api_key, persona_client=self.persona, verbose=verbose)

notte_sdk-1.4.0/src/notte_sdk/endpoints/agents.py

@@ -0,0 +1,323 @@
+import time
+from collections.abc import Sequence
+from typing import Unpack
+
+import requests
+from loguru import logger
+from pydantic import BaseModel
+from typing_extensions import final, override
+
+from notte_sdk.endpoints.base import BaseClient, NotteEndpoint
+from notte_sdk.types import (
+    AgentListRequest,
+    AgentResponse,
+    AgentRunRequest,
+    AgentRunRequestDict,
+    AgentStatus,
+    AgentStatusRequest,
+    AgentStatusRequestDict,
+    ListRequestDict,
+)
+from notte_sdk.types import AgentStatusResponse as _AgentStatusResponse
+
+
+# proxy for: StepAgentOutput
+class _AgentResponse(BaseModel):
+    state: BaseModel
+    actions: list[BaseModel]
+
+
+AgentStatusResponse = _AgentStatusResponse[_AgentResponse]
+
+
+@final
+class AgentsClient(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
+    AGENT_RUN = "run"
+    AGENT_STOP = "{agent_id}/stop"
+    AGENT_STATUS = "{agent_id}"
+    AGENT_LIST = ""
+    # The following endpoints downloads a .webp file
+    AGENT_REPLAY = "{agent_id}/replay"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        verbose: bool = False,
+    ):
+        """
+        Initialize an AgentsClient instance.
+
+        Configures the client to use the "agents" endpoint path and sets optional API key and server URL for authentication and server configuration. The initial state has no recorded agent response.
+
+        Args:
+            api_key: Optional API key for authenticating requests.
+        """
+        super().__init__(base_endpoint_path="agents", api_key=api_key, verbose=verbose)
+        self._last_agent_response: AgentResponse | None = None
+
+    @staticmethod
+    def agent_run_endpoint() -> NotteEndpoint[AgentResponse]:
+        """
+        Returns an endpoint for running an agent.
+
+        Creates a NotteEndpoint configured with the AGENT_RUN path, a POST method, and an expected AgentResponse.
+        """
+        return NotteEndpoint(path=AgentsClient.AGENT_RUN, response=AgentResponse, method="POST")
+
+    @staticmethod
+    def agent_stop_endpoint(agent_id: str | None = None) -> NotteEndpoint[AgentResponse]:
+        """
+        Constructs a DELETE endpoint for stopping an agent.
+
+        If an agent ID is provided, it is inserted into the endpoint URL. The returned
+        endpoint is configured with the DELETE HTTP method and expects an AgentStatusResponse.
+
+        Args:
+            agent_id (str, optional): The identifier of the agent to stop. If omitted,
+                the URL template will remain unformatted.
+
+        Returns:
+            NotteEndpoint[AgentResponse]: The endpoint object for stopping the agent.
+        """
+        path = AgentsClient.AGENT_STOP
+        if agent_id is not None:
+            path = path.format(agent_id=agent_id)
+        return NotteEndpoint(path=path, response=AgentStatusResponse, method="DELETE")
+
+    @staticmethod
+    def agent_status_endpoint(agent_id: str | None = None) -> NotteEndpoint[AgentStatusResponse]:
+        """
+        Creates an endpoint for retrieving an agent's status.
+
+        If an agent ID is provided, formats the endpoint path to target that specific agent.
+
+        Args:
+            agent_id: Optional identifier of the agent; if specified, the endpoint path will include this ID.
+
+        Returns:
+            NotteEndpoint configured with the GET method and AgentStatusResponse as the expected response.
+        """
+        path = AgentsClient.AGENT_STATUS
+        if agent_id is not None:
+            path = path.format(agent_id=agent_id)
+        return NotteEndpoint(path=path, response=AgentStatusResponse, method="GET")
+
+    @staticmethod
+    def agent_replay_endpoint(agent_id: str | None = None) -> NotteEndpoint[BaseModel]:
+        """
+        Creates an endpoint for downloading an agent's replay.
+        """
+        path = AgentsClient.AGENT_REPLAY
+        if agent_id is not None:
+            path = path.format(agent_id=agent_id)
+        return NotteEndpoint(path=path, response=BaseModel, method="GET")
+
+    @staticmethod
+    def agent_list_endpoint(params: AgentListRequest | None = None) -> NotteEndpoint[AgentResponse]:
+        """
+        Creates a NotteEndpoint for listing agents.
+
+        Returns an endpoint configured with the agent listing path and a GET method.
+        The optional params argument provides filtering or pagination details for the request.
+        """
+        return NotteEndpoint(
+            path=AgentsClient.AGENT_LIST,
+            response=AgentResponse,
+            method="GET",
+            request=None,
+            params=params,
+        )
+
+    @override
+    @staticmethod
+    def endpoints() -> Sequence[NotteEndpoint[BaseModel]]:
+        """
+        Returns a list of endpoints for agent operations.
+
+        Aggregates endpoints for running, stopping, checking status, and listing agents.
+        """
+        return [
+            AgentsClient.agent_run_endpoint(),
+            AgentsClient.agent_stop_endpoint(),
+            AgentsClient.agent_status_endpoint(),
+            AgentsClient.agent_list_endpoint(),
+            AgentsClient.agent_replay_endpoint(),
+        ]
+
+    @property
+    def agent_id(self) -> str | None:
+        """
+        Returns the agent ID from the last agent response, or None if no response exists.
+
+        This property retrieves the identifier from the most recent agent operation response.
+        If no agent has been run or if the response is missing, it returns None.
+        """
+        return self._last_agent_response.agent_id if self._last_agent_response is not None else None
+
+    def get_agent_id(self, agent_id: str | None = None) -> str:
+        """
+        Retrieves the agent ID to be used for agent operations.
+
+        If an `agent_id` is provided, it is returned directly. Otherwise, the method attempts to obtain the agent ID from the client's last agent response. Raises a ValueError if no agent ID is available.
+
+        Args:
+            agent_id (Optional[str]): An agent identifier. If omitted, the ID from the last agent response is used.
+
+        Raises:
+            ValueError: If no agent ID is provided and the client has no recorded agent response.
+
+        Returns:
+            str: The determined agent identifier.
+        """
+        if agent_id is None:
+            if self._last_agent_response is None:
+                raise ValueError("No agent to get agent id from")
+            agent_id = self._last_agent_response.agent_id
+        return agent_id
+
+    def run(self, **data: Unpack[AgentRunRequestDict]) -> AgentResponse:
+        """
+        Run an agent with the specified request parameters.
+
+        Validates the provided data using the AgentRunRequest model, sends a run request through the
+        designated endpoint, updates the last agent response, and returns the resulting AgentResponse.
+
+        Args:
+            **data: Keyword arguments representing the fields of an AgentRunRequest.
+
+        Returns:
+            AgentResponse: The response obtained from the agent run request.
+        """
+        request = AgentRunRequest.model_validate(data)
+        response = self.request(AgentsClient.agent_run_endpoint().with_request(request))
+        self._last_agent_response = response
+        return response
+
+    def wait_for_completion(
+        self,
+        agent_id: str | None = None,
+        polling_interval_seconds: int = 10,
+        max_attempts: int = 30,
+    ) -> AgentStatusResponse:
+        """
+        Waits for the specified agent to complete.
+
+        Args:
+            agent_id: The identifier of the agent to wait for.
+            polling_interval_seconds: The interval between status checks.
+            max_attempts: The maximum number of attempts to check the agent's status.
+
+        Returns:
+            AgentStatusResponse: The response from the agent status check.
+        """
+        agent_id = self.get_agent_id(agent_id)
+        last_step = 0
+        for _ in range(max_attempts):
+            response = self.status(agent_id=agent_id, replay=False)
+            if response.status == AgentStatus.closed:
+                return response
+            if len(response.steps) >= last_step:
+                for step in response.steps[last_step:]:
+                    for action in step.actions:
+                        logger.info(action.to_action().execution_message())  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType, reportAttributeAccessIssue]
+                last_step = len(response.steps)
+            logger.info(
+                f"Waiting {polling_interval_seconds} seconds for agent to complete (current step: {last_step})..."
+            )
+            time.sleep(polling_interval_seconds)
+        raise TimeoutError("Agent did not complete in time")
+
+    def close(self, agent_id: str) -> AgentResponse:
+        """
+        Stops the specified agent and clears the last agent response.
+
+        Retrieves a valid agent identifier using the provided value or the last stored
+        response, sends a stop request to the API, resets the internal agent response,
+        and returns the resulting AgentResponse.
+
+        Args:
+            agent_id: The identifier of the agent to stop.
+
+        Returns:
+            AgentResponse: The response from the stop operation.
+
+        Raises:
+            ValueError: If a valid agent identifier cannot be determined.
+        """
+        agent_id = self.get_agent_id(agent_id)
+        endpoint = AgentsClient.agent_stop_endpoint(agent_id=agent_id)
+        response = self.request(endpoint)
+        self._last_agent_response = None
+        return response
+
+    def status(self, **data: Unpack[AgentStatusRequestDict]) -> AgentStatusResponse:
+        """
+        Retrieves the status of the specified agent.
+
+        Queries the API for the current status of an agent using a validated agent ID.
+        The provided ID is confirmed (or obtained from the last response if needed), and the
+        resulting status is stored internally before being returned.
+
+        Args:
+            agent_id: Unique identifier of the agent to check.
+
+        Returns:
+            AgentResponse: The current status information of the specified agent.
+
+        Raises:
+            ValueError: If no valid agent ID can be determined.
+        """
+        agent_id = self.get_agent_id(data["agent_id"])
+        request = AgentStatusRequest.model_validate(data)
+        endpoint = AgentsClient.agent_status_endpoint(agent_id=agent_id).with_params(request)
+        response = self.request(endpoint)
+        self._last_agent_response = response
+        return response
+
+    def list(self, **data: Unpack[ListRequestDict]) -> Sequence[AgentResponse]:
+        """
+        Lists agents matching specified criteria.
+
+        Validates the keyword arguments using the AgentListRequest model, constructs
+        the corresponding endpoint for listing agents, and returns a sequence of agent
+        responses.
+
+        Args:
+            data: Arbitrary keyword arguments representing filter criteria for agents.
+
+        Returns:
+            A sequence of AgentResponse objects.
+        """
+        params = AgentListRequest.model_validate(data)
+        endpoint = AgentsClient.agent_list_endpoint(params=params)
+        return self.request_list(endpoint)
+
+    def replay(
+        self,
+        agent_id: str | None = None,
+        output_file: str | None = None,
+    ) -> bytes:
+        """
+        Downloads the replay for the specified agent in webp format.
+        """
+        agent_id = self.get_agent_id(agent_id)
+        endpoint = self.request_path(AgentsClient.agent_replay_endpoint(agent_id=agent_id))
+        response = requests.get(
+            url=endpoint,
+            headers=self.headers(),
+            timeout=self.DEFAULT_REQUEST_TIMEOUT_SECONDS,
+        )
+        if b"not found" in response.content:
+            raise ValueError(f"Replay for agent {agent_id} is not available.")
+        if output_file is not None:
+            with open(output_file, "wb") as f:
+                _ = f.write(response.content)
+        return response.content