smooth-py 0.2.6.dev20250922__tar.gz → 0.2.8.dev20251003__tar.gz

{smooth_py-0.2.6.dev20250922 → smooth_py-0.2.8.dev20251003}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: smooth-py
-Version: 0.2.6.dev20250922
+Version: 0.2.8.dev20251003
 Summary: 
 Author: Luca Pinchetti
 Author-email: luca@circlemind.co
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: mcp
+Requires-Dist: deprecated (>=1.2.18,<2.0.0)
 Requires-Dist: fastmcp (>=2.12.0,<3.0.0) ; extra == "mcp"
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
 Requires-Dist: pydantic (>=2.11.7,<3.0.0)

{smooth_py-0.2.6.dev20250922 → smooth_py-0.2.8.dev20251003}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "smooth-py"
-version = "0.2.6.dev20250922"
+version = "0.2.8.dev20251003"
 description = ""
 authors = [
     {name = "Luca Pinchetti",email = "luca@circlemind.co"}
@@ -10,7 +10,8 @@ requires-python = ">=3.10,<4.0"
 dependencies = [
     "pydantic (>=2.11.7,<3.0.0)",
     "httpx (>=0.28.1,<0.29.0)",
-    "requests (>=2.32.5,<3.0.0)"
+    "requests (>=2.32.5,<3.0.0)",
+    "deprecated (>=1.2.18,<2.0.0)"
 ]
 
 [project.optional-dependencies]

{smooth_py-0.2.6.dev20250922 → smooth_py-0.2.8.dev20251003}/src/smooth/__init__.py

@@ -6,12 +6,14 @@ import logging
 import os
 import time
 import urllib.parse
+import warnings
 from pathlib import Path
 from typing import Any, Literal, Type
 
 import httpx
 import requests
-from pydantic import BaseModel, Field
+from deprecated import deprecated
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 # Configure logging
 logger = logging.getLogger("smooth")
@@ -36,6 +38,7 @@ def _encode_url(url: str, interactive: bool = True, embed: bool = False) -> str:
 
 class TaskResponse(BaseModel):
   """Task response model."""
+  model_config = ConfigDict(extra='allow')
 
   id: str = Field(description="The ID of the task.")
   status: Literal["waiting", "running", "done", "failed"] = Field(description="The status of the task.")
@@ -67,13 +70,16 @@ class TaskRequest(BaseModel):
   allowed_urls: list[str] | None = Field(
     default=None,
     description=(
-      "List of allowed URL patterns using wildcard syntax (e.g., https://example.com/*). If None, all URLs are allowed."
+      "List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*). If None, all URLs are allowed."
     ),
   )
   enable_recording: bool = Field(default=True, description="Enable video recording of the task execution. Default is True")
-  session_id: str | None = Field(
+  profile_id: str | None = Field(
     default=None,
-    description="Browser session ID to use. Each session maintains its own state, such as login credentials.",
+    description=("Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials."),
+  )
+  profile_read_only: bool = Field(
+    default=False, description="If true, the profile specified by `profile_id` will be loaded in read-only mode."
   )
   stealth_mode: bool = Field(default=False, description="Run the browser in stealth mode.")
   proxy_server: str | None = Field(
@@ -84,29 +90,116 @@ class TaskRequest(BaseModel):
   )
   proxy_username: str | None = Field(default=None, description="Proxy server username.")
   proxy_password: str | None = Field(default=None, description="Proxy server password.")
+  experimental_features: dict[str, Any] | None = Field(
+    default=None, description="Experimental features to enable for the task."
+  )
+
+  @model_validator(mode="before")
+  @classmethod
+  def _handle_deprecated_session_id(cls, data: Any) -> Any:
+    if isinstance(data, dict) and "session_id" in data:
+      warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+      data["profile_id"] = data.pop("session_id")
+    return data
+
+  @property
+  def session_id(self):
+    """(Deprecated) Returns the session ID."""
+    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+    return self.profile_id
+
+  @session_id.setter
+  def session_id(self, value):
+    """(Deprecated) Sets the session ID."""
+    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+    self.profile_id = value
 
 
 class BrowserSessionRequest(BaseModel):
   """Request model for creating a browser session."""
 
-  session_id: str | None = Field(
-    default=None,
-    description=("The session ID to open in the browser. If None, a new session will be created with a random name."),
+  profile_id: str | None = Field(
+    default=None, description=("The profile ID to use for the browser session. If None, a new profile will be created.")
   )
   live_view: bool | None = Field(default=True, description="Request a live URL to interact with the browser session.")
 
+  @model_validator(mode="before")
+  @classmethod
+  def _handle_deprecated_session_id(cls, data: Any) -> Any:
+    if isinstance(data, dict) and "session_id" in data:
+      warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+      data["profile_id"] = data.pop("session_id")
+    return data
+
+  @property
+  def session_id(self):
+    """(Deprecated) Returns the session ID."""
+    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+    return self.profile_id
+
+  @session_id.setter
+  def session_id(self, value):
+    """(Deprecated) Sets the session ID."""
+    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+    self.profile_id = value
+
 
 class BrowserSessionResponse(BaseModel):
   """Browser session response model."""
 
-  session_id: str = Field(description="The ID of the browser session associated with the opened browser instance.")
+  profile_id: str = Field(description="The ID of the browser profile associated with the opened browser instance.")
   live_url: str | None = Field(default=None, description="The live URL to interact with the browser session.")
 
+  @model_validator(mode="before")
+  @classmethod
+  def _handle_deprecated_session_id(cls, data: Any) -> Any:
+    if isinstance(data, dict) and "session_id" in data:
+      warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+      data["profile_id"] = data.pop("session_id")
+    return data
+
+  @property
+  def session_id(self):
+    """(Deprecated) Returns the session ID."""
+    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+    return self.profile_id
+
+  @session_id.setter
+  def session_id(self, value):
+    """(Deprecated) Sets the session ID."""
+    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
+    self.profile_id = value
+
 
-class BrowserSessionsResponse(BaseModel):
-  """Response model for listing browser sessions."""
+class BrowserProfilesResponse(BaseModel):
+  """Response model for listing browser profiles."""
 
-  session_ids: list[str] = Field(description="The IDs of the browser sessions.")
+  profile_ids: list[str] = Field(description="The IDs of the browser profiles.")
+
+  @model_validator(mode="before")
+  @classmethod
+  def _handle_deprecated_session_ids(cls, data: Any) -> Any:
+    if isinstance(data, dict) and "session_ids" in data:
+      warnings.warn("'session_ids' is deprecated, use 'profile_ids' instead", DeprecationWarning, stacklevel=2)
+      data["profile_ids"] = data.pop("session_ids")
+    return data
+
+  @property
+  def session_ids(self):
+    """(Deprecated) Returns the session IDs."""
+    warnings.warn("'session_ids' is deprecated, use 'profile_ids' instead", DeprecationWarning, stacklevel=2)
+    return self.profile_ids
+
+  @session_ids.setter
+  def session_ids(self, value):
+    """(Deprecated) Sets the session IDs."""
+    warnings.warn("'session_ids' is deprecated, use 'profile_ids' instead", DeprecationWarning, stacklevel=2)
+    self.profile_ids = value
+
+
+class BrowserSessionsResponse(BrowserProfilesResponse):
+  """Response model for listing browser profiles."""
+  pass
 
 
 class UploadFileResponse(BaseModel):
@@ -189,9 +282,14 @@ class BrowserSessionHandle(BaseModel):
 
   browser_session: BrowserSessionResponse = Field(description="The browser session associated with this handle.")
 
+  @deprecated("session_id is deprecated, use profile_id instead")
   def session_id(self):
     """Returns the session ID for the browser session."""
-    return self.browser_session.session_id
+    return self.profile_id()
+
+  def profile_id(self):
+    """Returns the profile ID for the browser session."""
+    return self.browser_session.profile_id
 
   def live_url(self, interactive: bool = True, embed: bool = False):
     """Returns the live URL for the browser session."""
@@ -321,10 +419,13 @@ class SmoothClient(BaseClient):
     allowed_urls: list[str] | None = None,
     enable_recording: bool = False,
     session_id: str | None = None,
+    profile_id: str | None = None,
+    profile_read_only: bool = False,
     stealth_mode: bool = False,
     proxy_server: str | None = None,
     proxy_username: str | None = None,
     proxy_password: str | None = None,
+    experimental_features: dict[str, Any] | None = None,
   ) -> TaskHandle:
     """Runs a task and returns a handle to the task.
 
@@ -340,14 +441,17 @@ class SmoothClient(BaseClient):
         agent: The agent to use for the task.
         max_steps: Maximum number of steps the agent can take (max 64).
         device: Device type for the task. Default is mobile.
-        allowed_urls: List of allowed URL patterns using wildcard syntax (e.g., https://example.com/*).
+        allowed_urls: List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*).
           If None, all URLs are allowed.
         enable_recording: Enable video recording of the task execution.
-        session_id: Browser session ID to use.
+        session_id: (Deprecated, now `profile_id`) Browser session ID to use.
+        profile_id: Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials.
+        profile_read_only: If true, the profile specified by `profile_id` will be loaded in read-only mode.
         stealth_mode: Run the browser in stealth mode.
         proxy_server: Proxy server url to route browser traffic through.
         proxy_username: Proxy server username.
         proxy_password: Proxy server password.
+        experimental_features: Experimental features to enable for the task.
 
     Returns:
         A handle to the running task.
@@ -366,21 +470,26 @@ class SmoothClient(BaseClient):
       device=device,
       allowed_urls=allowed_urls,
       enable_recording=enable_recording,
-      session_id=session_id,
+      profile_id=profile_id or session_id,
+      profile_read_only=profile_read_only,
       stealth_mode=stealth_mode,
       proxy_server=proxy_server,
       proxy_username=proxy_username,
       proxy_password=proxy_password,
+      experimental_features=experimental_features,
     )
     initial_response = self._submit_task(payload)
 
     return TaskHandle(initial_response.id, self)
 
-  def open_session(self, session_id: str | None = None, live_view: bool = True) -> BrowserSessionHandle:
-    """Gets an interactive browser instance.
+  def open_session(
+    self, profile_id: str | None = None, session_id: str | None = None, live_view: bool = True
+  ) -> BrowserSessionHandle:
+    """Opens an interactive browser instance to interact with a specific browser profile.
 
     Args:
-        session_id: The session ID to associate with the browser. If None, a new session will be created.
+        profile_id: The profile ID to use for the session. If None, a new profile will be created.
+        session_id: (Deprecated, now `profile_id`) The session ID to associate with the browser.
         live_view: Whether to enable live view for the session.
 
     Returns:
@@ -392,7 +501,7 @@ class SmoothClient(BaseClient):
     try:
       response = self._session.post(
         f"{self.base_url}/browser/session",
-        json=BrowserSessionRequest(session_id=session_id, live_view=live_view).model_dump(exclude_none=True),
+        json=BrowserSessionRequest(profile_id=profile_id or session_id, live_view=live_view).model_dump(exclude_none=True),
       )
       data = self._handle_response(response)
       return BrowserSessionHandle(browser_session=BrowserSessionResponse(**data["r"]))
@@ -400,11 +509,11 @@ class SmoothClient(BaseClient):
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  def list_sessions(self) -> BrowserSessionsResponse:
-    """Lists all browser sessions for the user.
+  def list_profiles(self):
+    """Lists all browser profiles for the user.
 
     Returns:
-        A list of existing browser sessions.
+        A list of existing browser profiles.
 
     Raises:
         ApiException: If the API request fails.
@@ -412,20 +521,30 @@ class SmoothClient(BaseClient):
     try:
       response = self._session.get(f"{self.base_url}/browser/session")
       data = self._handle_response(response)
-      return BrowserSessionsResponse(**data["r"])
+      return BrowserProfilesResponse(**data["r"])
     except requests.exceptions.RequestException as e:
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  def delete_session(self, session_id: str):
-    """Delete a browser session."""
+  @deprecated("list_sessions is deprecated, use list_profiles instead")
+  def list_sessions(self):
+    """Lists all browser profiles for the user."""
+    return self.list_profiles()
+
+  def delete_profile(self, profile_id: str):
+    """Delete a browser profile."""
     try:
-      response = self._session.delete(f"{self.base_url}/browser/session/{session_id}")
+      response = self._session.delete(f"{self.base_url}/browser/session/{profile_id}")
       self._handle_response(response)
     except requests.exceptions.RequestException as e:
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
+  @deprecated("delete_session is deprecated, use delete_profile instead")
+  def delete_session(self, session_id: str):
+    """Delete a browser profile."""
+    self.delete_profile(session_id)
+
   def upload_file(self, file: io.IOBase, name: str | None = None, purpose: str | None = None) -> UploadFileResponse:
     """Upload a file and return the file ID.
 
@@ -588,10 +707,13 @@ class SmoothAsyncClient(BaseClient):
     allowed_urls: list[str] | None = None,
     enable_recording: bool = False,
     session_id: str | None = None,
+    profile_id: str | None = None,
+    profile_read_only: bool = False,
     stealth_mode: bool = False,
     proxy_server: str | None = None,
     proxy_username: str | None = None,
     proxy_password: str | None = None,
+    experimental_features: dict[str, Any] | None = None,
   ) -> AsyncTaskHandle:
     """Runs a task and returns a handle to the task asynchronously.
 
@@ -607,16 +729,17 @@ class SmoothAsyncClient(BaseClient):
         agent: The agent to use for the task.
         max_steps: Maximum number of steps the agent can take (max 64).
         device: Device type for the task. Default is mobile.
-        allowed_urls: List of allowed URL patterns using wildcard syntax (e.g., https://example.com/*).
+        allowed_urls: List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*).
           If None, all URLs are allowed.
         enable_recording: Enable video recording of the task execution.
-        session_id: Browser session ID to use.
+        session_id: (Deprecated, now `profile_id`) Browser session ID to use.
+        profile_id: Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials.
+        profile_read_only: If true, the profile specified by `profile_id` will be loaded in read-only mode.
         stealth_mode: Run the browser in stealth mode.
         proxy_server: Proxy server url to route browser traffic through.
         proxy_username: Proxy server username.
         proxy_password: Proxy server password.
-        poll_interval: The time in seconds to wait between polling for status.
-        timeout: The maximum time in seconds to wait for the task to complete.
+        experimental_features: Experimental features to enable for the task.
 
     Returns:
         A handle to the running task.
@@ -635,21 +758,26 @@ class SmoothAsyncClient(BaseClient):
       device=device,
       allowed_urls=allowed_urls,
       enable_recording=enable_recording,
-      session_id=session_id,
+      profile_id=profile_id or session_id,
+      profile_read_only=profile_read_only,
       stealth_mode=stealth_mode,
       proxy_server=proxy_server,
       proxy_username=proxy_username,
       proxy_password=proxy_password,
+      experimental_features=experimental_features,
     )
 
     initial_response = await self._submit_task(payload)
     return AsyncTaskHandle(initial_response.id, self)
 
-  async def open_session(self, session_id: str | None = None, live_view: bool = True) -> BrowserSessionHandle:
+  async def open_session(
+    self, profile_id: str | None = None, session_id: str | None = None, live_view: bool = True
+  ) -> BrowserSessionHandle:
     """Opens an interactive browser instance asynchronously.
 
     Args:
-        session_id: The session ID to associate with the browser.
+        session_id: (Deprecated, now `profile_id`) The session ID to associate with the browser.
+        profile_id: The profile ID to associate with the browser.
         live_view: Whether to enable live view for the session.
 
     Returns:
@@ -661,7 +789,7 @@ class SmoothAsyncClient(BaseClient):
     try:
       response = await self._client.post(
         f"{self.base_url}/browser/session",
-        json=BrowserSessionRequest(session_id=session_id, live_view=live_view).model_dump(exclude_none=True),
+        json=BrowserSessionRequest(profile_id=profile_id or session_id, live_view=live_view).model_dump(exclude_none=True),
       )
       data = self._handle_response(response)
       return BrowserSessionHandle(browser_session=BrowserSessionResponse(**data["r"]))
@@ -669,11 +797,11 @@ class SmoothAsyncClient(BaseClient):
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  async def list_sessions(self) -> BrowserSessionsResponse:
-    """Lists all browser sessions for the user.
+  async def list_profiles(self):
+    """Lists all browser profiles for the user.
 
     Returns:
-        A list of existing browser sessions.
+        A list of existing browser profiles.
 
     Raises:
         ApiException: If the API request fails.
@@ -681,20 +809,30 @@ class SmoothAsyncClient(BaseClient):
     try:
       response = await self._client.get(f"{self.base_url}/browser/session")
       data = self._handle_response(response)
-      return BrowserSessionsResponse(**data["r"])
+      return BrowserProfilesResponse(**data["r"])
     except httpx.RequestError as e:
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  async def delete_session(self, session_id: str):
-    """Delete a browser session."""
+  @deprecated("list_sessions is deprecated, use list_profiles instead")
+  async def list_sessions(self):
+    """Lists all browser profiles for the user."""
+    return await self.list_profiles()
+
+  async def delete_profile(self, profile_id: str):
+    """Delete a browser profile."""
     try:
-      response = await self._client.delete(f"{self.base_url}/browser/session/{session_id}")
+      response = await self._client.delete(f"{self.base_url}/browser/session/{profile_id}")
       self._handle_response(response)
     except httpx.RequestError as e:
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
+  @deprecated("delete_session is deprecated, use delete_profile instead")
+  async def delete_session(self, session_id: str):
+    """Delete a browser profile."""
+    await self.delete_profile(session_id)
+
   async def upload_file(self, file: io.IOBase, name: str | None = None, purpose: str | None = None) -> UploadFileResponse:
     """Upload a file and return the file ID.