smooth-py 0.1.1.post0__py3-none-any.whl → 0.1.2.post0__py3-none-any.whl

smooth/__init__.py

@@ -4,11 +4,14 @@ import asyncio
 import logging
 import os
 import time
-from typing import Any, Dict, Literal, Optional, TypeVar, Union
+from typing import (
+  Any,
+  Literal,
+)
 
 import httpx
 import requests
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, Field
 
 # Configure logging
 logger = logging.getLogger("smooth")
@@ -23,45 +26,49 @@ BASE_URL = "https://api2.circlemind.co/api/"
 class TaskResponse(BaseModel):
   """Task response model."""
 
-  model_config = ConfigDict(extra="forbid")
-
   id: str = Field(description="The ID of the task.")
   status: Literal["waiting", "running", "done", "failed"] = Field(description="The status of the task.")
-  result: Any | None = Field(default=None, description="The result of the task if successful.")
-  error: str | None = Field(default=None, description="Error message if the task failed.")
+  output: Any | None = Field(default=None, description="The output of the task.")
   credits_used: int | None = Field(default=None, description="The amount of credits used to perform the task.")
-  src: str | None = Field(default=None, description="")
+  device: Literal["desktop", "mobile"] | None = Field(default=None, description="The device type used for the task.")
+  live_url: str | None = Field(default=None, description="The URL to view and interact with the task execution.")
+  recording_url: str | None = Field(default=None, description="The URL to view the task recording.")
 
 
 class TaskRequest(BaseModel):
   """Run task request model."""
 
-  model_config = ConfigDict(extra="forbid")
-
   task: str = Field(description="The task to run.")
   agent: Literal["smooth"] = Field(default="smooth", description="The agent to use for the task.")
-  max_steps: int = Field(default=32, ge=1, le=64, description="Maximum number of steps the agent can take (max 64).")
+  max_steps: int = Field(default=32, ge=2, le=128, description="Maximum number of steps the agent can take (min 2, max 128).")
   device: Literal["desktop", "mobile"] = Field(default="mobile", description="Device type for the task. Default is mobile.")
-  session_id: Optional[str] = Field(
+  enable_recording: bool = Field(default=False, description="Enable video recording of the task execution. Default is False")
+  session_id: str | None = Field(
     default=None,
-    description="(optional) Browser session ID to use. Each session maintains its own state, such as login credentials.",
+    description="Browser session ID to use. Each session maintains its own state, such as login credentials.",
   )
-  stealth_mode: bool = Field(default=False, description="(optional) Run the browser in stealth mode.")
-  proxy_server: Optional[str] = Field(
+  stealth_mode: bool = Field(default=False, description="Run the browser in stealth mode.")
+  proxy_server: str | None = Field(
     default=None,
     description=(
-      "(optional) Proxy server url to route browser traffic through."
-      " Must include the protocol to use (e.g. http:// or https://)"
+      "Proxy server url to route browser traffic through." " Must include the protocol to use (e.g. http:// or https://)"
     ),
   )
-  proxy_username: Optional[str] = Field(default=None, description="(optional) Proxy server username.")
-  proxy_password: Optional[str] = Field(default=None, description="(optional) Proxy server password.")
+  proxy_username: str | None = Field(default=None, description="Proxy server username.")
+  proxy_password: str | None = Field(default=None, description="Proxy server password.")
 
 
-class BrowserResponse(BaseModel):
-  """Browser session response model."""
+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."),
+  )
 
-  model_config = ConfigDict(extra="forbid")
+
+class BrowserSessionResponse(BaseModel):
+  """Browser session response model."""
 
   live_url: str = Field(description="The live URL to interact with the browser session.")
   session_id: str = Field(description="The ID of the browser session associated with the opened browser instance.")
@@ -71,12 +78,6 @@ class BrowserSessionsResponse(BaseModel):
   """Response model for listing browser sessions."""
 
   session_ids: list[str] = Field(description="The IDs of the browser sessions.")
-  session_names: list[str | None] = Field(
-    description="The names of the browser sessions (only useful to uniquely identify them)."
-  )
-
-
-T = TypeVar("T")
 
 
 # --- Exception Handling ---
@@ -85,7 +86,7 @@ T = TypeVar("T")
 class ApiError(Exception):
   """Custom exception for API errors."""
 
-  def __init__(self, status_code: int, detail: str, response_data: Optional[Dict[str, Any]] = None):
+  def __init__(self, status_code: int, detail: str, response_data: dict[str, Any] | None = None):
     """Initializes the API error."""
     self.status_code = status_code
     self.detail = detail
@@ -105,7 +106,7 @@ class TimeoutError(Exception):
 class BaseClient:
   """Base client for handling common API interactions."""
 
-  def __init__(self, api_key: Optional[str] = None, base_url: str = BASE_URL, api_version: str = "v1"):
+  def __init__(self, api_key: str | None = None, base_url: str = BASE_URL, api_version: str = "v1"):
     """Initializes the base client."""
     # Try to get API key from environment if not provided
     if not api_key:
@@ -122,10 +123,10 @@ class BaseClient:
     self.headers = {
       "apikey": self.api_key,
       "Content-Type": "application/json",
-      "User-Agent": "smooth-python-sdk/0.1.0",
+      "User-Agent": "smooth-python-sdk/0.1.1",
     }
 
-  def _handle_response(self, response: Union[requests.Response, httpx.Response]) -> dict[str, Any]:
+  def _handle_response(self, response: requests.Response | httpx.Response) -> dict[str, Any]:
     """Handles HTTP responses and raises exceptions for errors."""
     if 200 <= response.status_code < 300:
       try:
@@ -143,18 +144,44 @@ class BaseClient:
       detail = response.text or f"HTTP {response.status_code} error"
 
     logger.error(f"API error: {response.status_code} - {detail}")
-    raise ApiError(
-      status_code=response.status_code, detail=detail, response_data=error_data
-    )
+    raise ApiError(status_code=response.status_code, detail=detail, response_data=error_data)
 
 
 # --- Synchronous Client ---
 
 
-class SyncClient(BaseClient):
+class TaskHandle:
+  """A handle to a running task."""
+
+  def __init__(self, task_id: str, client: "SmoothClient", live_url: str | None, poll_interval: int, timeout: int | None):
+    """Initializes the task handle."""
+    self._client = client
+    self._poll_interval = poll_interval
+    self._timeout = timeout
+    self._task_response: TaskResponse | None = None
+
+    self.id = task_id
+    self.live_url = live_url
+
+  def result(self) -> TaskResponse:
+    """Waits for the task to complete and returns the result."""
+    if self._task_response and self._task_response.status not in ["running", "waiting"]:
+      return self._task_response
+
+    start_time = time.time()
+    while self._timeout is None or (time.time() - start_time) < self._timeout:
+      task_response = self._client._get_task(self.id)  # pyright: ignore [reportPrivateUsage]
+      if task_response.status not in ["running", "waiting"]:
+        self._task_response = task_response
+        return task_response
+      time.sleep(self._poll_interval)
+    raise TimeoutError(f"Task {self.id} did not complete within {self._timeout} seconds.")
+
+
+class SmoothClient(BaseClient):
   """A synchronous client for the API."""
 
-  def __init__(self, api_key: Optional[str] = None, base_url: str = BASE_URL, api_version: str = "v1"):
+  def __init__(self, api_key: str | None = None, base_url: str = BASE_URL, api_version: str = "v1"):
     """Initializes the synchronous client."""
     super().__init__(api_key, base_url, api_version)
     self._session = requests.Session()
@@ -173,18 +200,8 @@ class SyncClient(BaseClient):
     if hasattr(self, "_session"):
       self._session.close()
 
-  def run_task(self, payload: TaskRequest) -> TaskResponse:
-    """Submits a task to be run.
-
-    Args:
-        payload: The request object containing task details.
-
-    Returns:
-        The initial response for the submitted task.
-
-    Raises:
-        ApiException: If the API request fails.
-    """
+  def _submit_task(self, payload: TaskRequest) -> TaskResponse:
+    """Submits a task to be run."""
     try:
       response = self._session.post(f"{self.base_url}/task", json=payload.model_dump(exclude_none=True))
       data = self._handle_response(response)
@@ -193,19 +210,8 @@ class SyncClient(BaseClient):
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  def get_task(self, task_id: str) -> TaskResponse:
-    """Retrieves the status and result of a task.
-
-    Args:
-        task_id: The ID of the task to retrieve.
-
-    Returns:
-        The current status and data of the task.
-
-    Raises:
-        ApiException: If the API request fails.
-        ValueError: If task_id is empty.
-    """
+  def _get_task(self, task_id: str) -> TaskResponse:
+    """Retrieves the status and result of a task."""
     if not task_id:
       raise ValueError("Task ID cannot be empty.")
 
@@ -217,23 +223,44 @@ class SyncClient(BaseClient):
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  def run_and_wait_for_task(self, payload: TaskRequest, poll_interval: int = 1, timeout: int = 60 * 15) -> TaskResponse:
-    """Runs a task and waits for it to complete.
-
-    This method submits a task and then polls the get_task endpoint
-    until the task's status is no longer 'running' or 'waiting'.
+  def run(
+    self,
+    task: str,
+    poll_interval: int = 1,
+    timeout: int = 60 * 15,
+    agent: Literal["smooth"] = "smooth",
+    max_steps: int = 32,
+    device: Literal["desktop", "mobile"] = "mobile",
+    enable_recording: bool = False,
+    session_id: str | None = None,
+    stealth_mode: bool = False,
+    proxy_server: str | None = None,
+    proxy_username: str | None = None,
+    proxy_password: str | None = None,
+  ) -> TaskHandle:
+    """Runs a task and returns a handle to the task.
+
+    This method submits a task and returns a `TaskHandle` object
+    that can be used to get the result of the task.
 
     Args:
-        payload: The request object containing task details.
+        task: The task to run.
         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.
-        progress_callback: Optional callback function called with TaskResponse on each poll.
+        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.
+        enable_recording: Enable video recording of the task execution.
+        session_id: Browser session ID to use.
+        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.
 
     Returns:
-        The final response of the completed or failed task.
+        A handle to the running task.
 
     Raises:
-        TimeoutError: If the task does not complete within the specified timeout.
         ApiException: If the API request fails.
     """
     if poll_interval < 0.1:
@@ -241,26 +268,31 @@ class SyncClient(BaseClient):
     if timeout < 1:
       raise ValueError("Timeout must be at least 1 second.")
 
+    payload = TaskRequest(
+      task=task,
+      agent=agent,
+      max_steps=max_steps,
+      device=device,
+      enable_recording=enable_recording,
+      session_id=session_id,
+      stealth_mode=stealth_mode,
+      proxy_server=proxy_server,
+      proxy_username=proxy_username,
+      proxy_password=proxy_password,
+    )
+    initial_response = self._submit_task(payload)
     start_time = time.time()
-    initial_response = self.run_task(payload)
-    task_id = initial_response.id
-
-    while (time.time() - start_time) < timeout:
-      task_response = self.get_task(task_id)
-
-      if task_response.status not in ["running", "waiting"]:
-        return task_response
-
+    while time.time() - start_time < 16 and initial_response.live_url is None:
+      initial_response = self._get_task(initial_response.id)
       time.sleep(poll_interval)
 
-    raise TimeoutError(f"Task {task_id} did not complete within {timeout} seconds.")
+    return TaskHandle(initial_response.id, self, initial_response.live_url, poll_interval, timeout)
 
-  def get_browser(self, session_id: Optional[str] = None, session_name: Optional[str] = None) -> BrowserResponse:
+  def open_session(self, session_id: str | None = None) -> BrowserSessionResponse:
     """Gets an interactive browser instance.
 
     Args:
         session_id: The session ID to associate with the browser. If None, a new session will be created.
-        session_name: The name to associate to the new browser session. Ignored if a valid session_id is provided.
 
     Returns:
         The browser session details, including the live URL.
@@ -268,16 +300,13 @@ class SyncClient(BaseClient):
     Raises:
         ApiException: If the API request fails.
     """
-    params: dict[str, Any] = {}
-    if session_id:
-      params["session_id"] = session_id
-    if session_name:
-      params["session_name"] = session_name
-
     try:
-      response = self._session.get(f"{self.base_url}/browser", params=params)
+      response = self._session.post(
+        f"{self.base_url}/browser/session",
+        json=BrowserSessionRequest(session_id=session_id).model_dump(exclude_none=True),
+      )
       data = self._handle_response(response)
-      return BrowserResponse(**data["r"])
+      return BrowserSessionResponse(**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
@@ -299,14 +328,51 @@ class SyncClient(BaseClient):
       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."""
+    try:
+      response = self._session.delete(f"{self.base_url}/browser/session/{session_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
+
 
 # --- Asynchronous Client ---
 
 
-class AsyncClient(BaseClient):
+class AsyncTaskHandle:
+  """An asynchronous handle to a running task."""
+
+  def __init__(self, task_id: str, client: "SmoothAsyncClient", live_url: str | None, poll_interval: int, timeout: int | None):
+    """Initializes the asynchronous task handle."""
+    self._client = client
+    self._poll_interval = poll_interval
+    self._timeout = timeout
+    self._task_response: TaskResponse | None = None
+
+    self.id = task_id
+    self.live_url = live_url
+
+  async def result(self) -> TaskResponse:
+    """Waits for the task to complete and returns the result."""
+    if self._task_response and self._task_response.status not in ["running", "waiting"]:
+      return self._task_response
+
+    start_time = time.time()
+    while self._timeout is None or (time.time() - start_time) < self._timeout:
+      task_response = await self._client._get_task(self.id)  # pyright: ignore [reportPrivateUsage]
+      if task_response.status not in ["running", "waiting"]:
+        self._task_response = task_response
+        return task_response
+      await asyncio.sleep(self._poll_interval)
+    raise TimeoutError(f"Task {self.id} did not complete within {self._timeout} seconds.")
+
+
+class SmoothAsyncClient(BaseClient):
   """An asynchronous client for the API."""
 
-  def __init__(self, api_key: Optional[str] = None, base_url: str = BASE_URL, api_version: str = "v1", timeout: int = 30):
+  def __init__(self, api_key: str | None = None, base_url: str = BASE_URL, api_version: str = "v1", timeout: int = 30):
     """Initializes the asynchronous client."""
     super().__init__(api_key, base_url, api_version)
     self._client = httpx.AsyncClient(headers=self.headers, timeout=timeout)
@@ -319,18 +385,8 @@ class AsyncClient(BaseClient):
     """Exits the asynchronous context manager."""
     await self.close()
 
-  async def run_task(self, payload: TaskRequest) -> TaskResponse:
-    """Submits a task to be run asynchronously.
-
-    Args:
-        payload: The request object containing task details.
-
-    Returns:
-        The initial response for the submitted task.
-
-    Raises:
-        ApiException: If the API request fails.
-    """
+  async def _submit_task(self, payload: TaskRequest) -> TaskResponse:
+    """Submits a task to be run asynchronously."""
     try:
       response = await self._client.post(f"{self.base_url}/task", json=payload.model_dump(exclude_none=True))
       data = self._handle_response(response)
@@ -339,19 +395,8 @@ class AsyncClient(BaseClient):
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  async def get_task(self, task_id: str) -> TaskResponse:
-    """Retrieves the status and result of a task asynchronously.
-
-    Args:
-        task_id: The ID of the task to retrieve.
-
-    Returns:
-        The current status and data of the task.
-
-    Raises:
-        ApiException: If the API request fails.
-        ValueError: If task_id is empty.
-    """
+  async def _get_task(self, task_id: str) -> TaskResponse:
+    """Retrieves the status and result of a task asynchronously."""
     if not task_id:
       raise ValueError("Task ID cannot be empty.")
 
@@ -363,23 +408,44 @@ class AsyncClient(BaseClient):
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  async def run_and_wait_for_task(self, payload: TaskRequest, poll_interval: int = 1, timeout: int = 60 * 15) -> TaskResponse:
-    """Runs a task and waits for it to complete asynchronously.
-
-    This method submits a task and then polls the get_task endpoint
-    until the task's status is no longer 'RUNNING' or 'waiting'.
+  async def run(
+    self,
+    task: str,
+    poll_interval: int = 1,
+    timeout: int = 60 * 15,
+    agent: Literal["smooth"] = "smooth",
+    max_steps: int = 32,
+    device: Literal["desktop", "mobile"] = "mobile",
+    enable_recording: bool = False,
+    session_id: str | None = None,
+    stealth_mode: bool = False,
+    proxy_server: str | None = None,
+    proxy_username: str | None = None,
+    proxy_password: str | None = None,
+  ) -> AsyncTaskHandle:
+    """Runs a task and returns a handle to the task asynchronously.
+
+    This method submits a task and returns an `AsyncTaskHandle` object
+    that can be used to get the result of the task.
 
     Args:
-        payload: The request object containing task details.
+        task: The task to run.
         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.
-        progress_callback: Optional async callback function called with TaskResponse on each poll.
+        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.
+        enable_recording: Enable video recording of the task execution.
+        session_id: Browser session ID to use.
+        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.
 
     Returns:
-        The final response of the completed or failed task.
+        A handle to the running task.
 
     Raises:
-        TimeoutError: If the task does not complete within the specified timeout.
         ApiException: If the API request fails.
     """
     if poll_interval < 0.1:
@@ -387,29 +453,31 @@ class AsyncClient(BaseClient):
     if timeout < 1:
       raise ValueError("Timeout must be at least 1 second.")
 
-    start_time = time.time()
-    initial_response = await self.run_task(payload)
-    task_id = initial_response.id
-
-    logger.info(f"Task {task_id} started, polling every {poll_interval}s for up to {timeout}s")
-
-    while (time.time() - start_time) < timeout:
-      task_status = await self.get_task(task_id)
-
-      if task_status.status.lower() not in ["running", "waiting"]:
-        logger.info(f"Task {task_id} completed with status: {task_status.status}")
-        return task_status
+    payload = TaskRequest(
+      task=task,
+      agent=agent,
+      max_steps=max_steps,
+      device=device,
+      enable_recording=enable_recording,
+      session_id=session_id,
+      stealth_mode=stealth_mode,
+      proxy_server=proxy_server,
+      proxy_username=proxy_username,
+      proxy_password=proxy_password,
+    )
 
+    initial_response = await self._submit_task(payload)
+    start_time = time.time()
+    while time.time() - start_time < 16 and initial_response.live_url is None:
+      initial_response = await self._get_task(initial_response.id)
       await asyncio.sleep(poll_interval)
+    return AsyncTaskHandle(initial_response.id, self, initial_response.live_url, poll_interval, timeout)
 
-    raise TimeoutError(f"Task {task_id} did not complete within {timeout} seconds.")
-
-  async def get_browser(self, session_id: Optional[str] = None, session_name: Optional[str] = None) -> BrowserResponse:
-    """Gets an interactive browser instance asynchronously.
+  async def open_session(self, session_id: str | None = None) -> BrowserSessionResponse:
+    """Opens an interactive browser instance asynchronously.
 
     Args:
         session_id: The session ID to associate with the browser.
-        session_name: The name for a new browser session.
 
     Returns:
         The browser session details, including the live URL.
@@ -417,16 +485,13 @@ class AsyncClient(BaseClient):
     Raises:
         ApiException: If the API request fails.
     """
-    params: dict[str, Any] = {}
-    if session_id:
-      params["session_id"] = session_id
-    if session_name:
-      params["session_name"] = session_name
-
     try:
-      response = await self._client.get(f"{self.base_url}/browser", params=params)
+      response = await self._client.post(
+        f"{self.base_url}/browser/session",
+        json=BrowserSessionRequest(session_id=session_id).model_dump(exclude_none=True),
+      )
       data = self._handle_response(response)
-      return BrowserResponse(**data["r"])
+      return BrowserSessionResponse(**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
@@ -448,6 +513,15 @@ class AsyncClient(BaseClient):
       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."""
+    try:
+      response = await self._client.delete(f"{self.base_url}/browser/session/{session_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
+
   async def close(self):
     """Closes the async client session."""
     await self._client.aclose()

smooth_py-0.1.2.post0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.3
+Name: smooth-py
+Version: 0.1.2.post0
+Summary: 
+Author: Luca Pinchetti
+Author-email: luca@circlemind.co
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.11.7,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Smooth Python SDK
+
+The Smooth Python SDK provides a convenient way to interact with the Smooth API for programmatic browser automation and task execution.
+
+## Features
+
+*   **Synchronous and Asynchronous Clients**: Choose between `SmoothClient` for traditional sequential programming and `SmoothAsyncClient` for high-performance asynchronous applications.
+*   **Task Management**: Easily run tasks and retrieve results upon completion.
+*   **Interactive Browser Sessions**: Get access to, interact with, and delete stateful browser sessions to manage your login credentials.
+*   **Advanced Task Configuration**: Customize task execution with options for device type, session recording, stealth mode, and proxy settings.
+
+## Installation
+
+You can install the Smooth Python SDK using pip:
+
+```bash
+pip install smooth-py
+```
+
+## Authentication
+
+The SDK requires an API key for authentication. You can provide the API key in two ways:
+
+1.  **Directly in the client constructor**:
+
+    ```python
+    from smooth import SmoothClient
+
+    client = SmoothClient(api_key="YOUR_API_KEY")
+    ```
+
+2.  **As an environment variable**:
+
+    Set the `CIRCLEMIND_API_KEY` environment variable, and the client will automatically use it.
+
+    ```bash
+    export CIRCLEMIND_API_KEY="YOUR_API_KEY"
+    ```
+
+    ```python
+    from smooth import SmoothClient
+
+    # The client will pick up the API key from the environment variable
+    client = SmoothClient()
+    ```
+
+## Usage
+
+### Synchronous Client
+
+The `SmoothClient` is ideal for scripts and applications that don't require asynchronous operations.
+
+#### Running a Task and Waiting for the Result
+
+The `run` method returns a `TaskHandle`. You can use the `result()` method on this handle to wait for the task to complete and get its final state.
+
+```python
+from smooth import SmoothClient
+from smooth.models import ApiError, TimeoutError
+
+with SmoothClient() as client:
+    try:
+        # The run method returns a handle to the task immediately
+        task_handle = client.run(
+            task="Go to https://www.google.com and search for 'Smooth SDK'",
+            device="desktop",
+            enable_recording=True
+        )
+        print(f"Task submitted with ID: {task_handle.id}")
+        print(f"Live view available at: {task_handle.live_url}")
+
+        # The result() method waits for the task to complete
+        completed_task = task_handle.result()
+        
+        if completed_task.status == "done":
+            print("Task Result:", completed_task.output)
+            print(f"View recording at: {completed_task.recording_url}")
+        else:
+            print("Task Failed:", completed_task.output)
+            
+    except TimeoutError:
+        print("The task timed out.")
+    except ApiError as e:
+        print(f"An API error occurred: {e}")
+```
+
+#### Managing Browser Sessions
+
+You can create, list, and delete browser sessions to maintain state (like logins) between tasks.
+
+```python
+from smooth import SmoothClient
+
+with SmoothClient() as client:
+    # Create a new browser session
+    browser_session = client.open_session()
+    print("Live URL:", browser_session.live_url)
+    print("Session ID:", browser_session.session_id)
+
+    # List all browser sessions
+    sessions = client.list_sessions()
+    print("All Session IDs:", sessions.session_ids)
+
+    # Delete the browser session
+    client.delete_session(session_id=session_id)
+    print(f"Session '{session_id}' deleted.")
+```
+
+### Asynchronous Client
+
+The `SmoothAsyncClient` is designed for use in asynchronous applications, such as those built with `asyncio`, to handle multiple operations concurrently without blocking.
+
+#### Running a Task and Waiting for the Result
+
+The `run` method returns an `AsyncTaskHandle`. Await the `result()` method on the handle to get the final task status.
+
+```python
+import asyncio
+from smooth import SmoothAsyncClient
+from smooth.models import ApiError, TimeoutError
+
+async def main():
+    async with SmoothAsyncClient() as client:
+        try:
+            # The run method returns a handle to the task immediately
+            task_handle = await client.run(
+                task="Go to Github and search for \"smooth-sdk\""
+            )
+            print(f"Task submitted with ID: {task_handle.id}")
+            print(f"Live view available at: {task_handle.live_url}")
+
+            # The result() method waits for the task to complete
+            completed_task = await task_handle.result()
+            
+            if completed_task.status == "done":
+                print("Task Result:", completed_task.output)
+            else:
+                print("Task Failed:", completed_task.output)
+                
+        except TimeoutError:
+            print("The task timed out.")
+        except ApiError as e:
+            print(f"An API error occurred: {e}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+

smooth_py-0.1.2.post0.dist-info/RECORD

@@ -0,0 +1,4 @@
+smooth/__init__.py,sha256=65IQjCGmh5xRFfOk-48V_NNgItnh7uUCSva_PYGHd5I,19326
+smooth_py-0.1.2.post0.dist-info/METADATA,sha256=WveUBUPZIOGiNvYT1fEB47GOk4SuGRkxIhv_4oqYQpA,5394
+smooth_py-0.1.2.post0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+smooth_py-0.1.2.post0.dist-info/RECORD,,

smooth_py-0.1.1.post0.dist-info/METADATA

@@ -1,161 +0,0 @@
-Metadata-Version: 2.3
-Name: smooth-py
-Version: 0.1.1.post0
-Summary: 
-Author: Luca Pinchetti
-Author-email: luca@circlemind.co
-Requires-Python: >=3.10
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: httpx (>=0.28.1,<0.29.0)
-Requires-Dist: pydantic (>=2.11.7,<3.0.0)
-Description-Content-Type: text/markdown
-
-# Smooth Python SDK
-
-The Smooth Python SDK provides a convenient way to interact with the Smooth API for programmatic browser automation and task execution. This SDK includes both synchronous and asynchronous clients to suit different programming needs.
-
-## Features
-
-*   **Synchronous and Asynchronous Clients**: Choose between `SyncClient` for traditional sequential programming and `AsyncClient` for high-performance asynchronous applications.
-*   **Task Management**: Easily run tasks, check their status, and retrieve results.
-*   **Interactive Browser Sessions**: Get access to and manage interactive browser sessions.
-
-## Installation
-
-You can install the Smooth Python SDK using pip:
-
-```bash
-pip install smooth-py
-```
-
-## Authentication
-
-The SDK requires an API key for authentication. You can provide the API key in two ways:
-
-1.  **Directly in the client constructor**:
-
-    ```python
-    from smooth import SyncClient
-
-    client = SyncClient(api_key="YOUR_API_KEY")
-    ```
-
-2.  **As an environment variable**:
-
-    Set the `CIRCLEMIND_API_KEY` environment variable, and the client will automatically use it.
-
-    ```bash
-    export CIRCLEMIND_API_KEY="YOUR_API_KEY"
-    ```
-
-    ```python
-    from smooth import SyncClient
-
-    # The client will pick up the API key from the environment variable
-    client = SyncClient()
-    ```
-
-## Usage
-
-### Synchronous Client
-
-The `SyncClient` is ideal for scripts and applications that don't require asynchronous operations.
-
-#### Running a Task and Waiting for the Result
-
-```python
-from smooth import SyncClient, TaskRequest
-
-with SyncClient() as client:
-    task_payload = TaskRequest(
-        task="Go to https://www.google.com and search for 'Smooth SDK'"
-    )
-    
-    try:
-        completed_task = client.run_and_wait_for_task(task_payload)
-        
-        if completed_task.result:
-            print("Task Result:", completed_task.result)
-        else:
-            print("Task Error:", completed_task.error)
-            
-    except TimeoutError:
-        print("The task timed out.")
-    except ApiError as e:
-        print(f"An API error occurred: {e}")
-```
-
-#### Managing Browser Sessions
-
-```python
-from smooth import SyncClient
-
-with SyncClient() as client:
-    # Get a new browser session
-    browser_session = client.get_browser(session_name="my-test-session")
-    print("Live URL:", browser_session.live_url)
-    print("Session ID:", browser_session.session_id)
-
-    # List all browser sessions
-    sessions = client.list_sessions()
-    print("All Session IDs:", sessions.session_ids)
-```
-
-### Asynchronous Client
-
-The `AsyncClient` is designed for use in asynchronous applications, such as those built with `asyncio`, to handle multiple operations concurrently without blocking.
-
-#### Running a Task and Waiting for the Result
-
-```python
-import asyncio
-from smooth import AsyncClient, TaskRequest
-
-async def main():
-    async with AsyncClient() as client:
-        task_payload = TaskRequest(
-            task="Go to Github and search for \"smooth-sdk\""
-        )
-        
-        try:
-            completed_task = await client.run_and_wait_for_task(task_payload)
-            
-            if completed_task.result:
-                print("Task Result:", completed_task.result)
-            else:
-                print("Task Error:", completed_task.error)
-                
-        except TimeoutError:
-            print("The task timed out.")
-        except ApiError as e:
-            print(f"An API error occurred: {e}")
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-#### Managing Browser Sessions
-
-```python
-import asyncio
-from smooth import AsyncClient
-
-async def main():
-    async with AsyncClient() as client:
-        # Get a new browser session
-        browser_session = await client.get_browser(session_name="my-async-session")
-        print("Live URL:", browser_session.live_url)
-        print("Session ID:", browser_session.session_id)
-
-        # List all browser sessions
-        sessions = await client.list_sessions()
-        print("All Session IDs:", sessions.session_ids)
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-

smooth_py-0.1.1.post0.dist-info/RECORD

@@ -1,4 +0,0 @@
-smooth/__init__.py,sha256=cAEweO-FSsk9eIAp_068Gm1s8FdylhRKV9W707kNX88,15745
-smooth_py-0.1.1.post0.dist-info/METADATA,sha256=1FsW9jkuCBaE085DcMd0PzYE-fM7mLXx8i0JxQzWC8Y,4645
-smooth_py-0.1.1.post0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-smooth_py-0.1.1.post0.dist-info/RECORD,,