lmnr 0.4.53.dev0__py3-none-any.whl → 0.7.26__py3-none-any.whl

lmnr/sdk/browser/utils.py

@@ -0,0 +1,70 @@
+import asyncio
+import logging
+import time
+
+from lmnr.sdk.client.asynchronous.async_client import AsyncLaminarClient
+from lmnr.sdk.client.synchronous.sync_client import LaminarClient
+
+logger = logging.getLogger(__name__)
+
+
+def with_tracer_wrapper(func):
+    """Helper for providing tracer for wrapper functions."""
+
+    def _with_tracer(tracer, to_wrap):
+        def wrapper(wrapped, instance, args, kwargs):
+            return func(tracer, to_wrap, wrapped, instance, args, kwargs)
+
+        return wrapper
+
+    return _with_tracer
+
+
+def with_tracer_and_client_wrapper(func):
+    """Helper for providing tracer and client for wrapper functions."""
+
+    def _with_tracer_and_client(
+        tracer, client: LaminarClient | AsyncLaminarClient, to_wrap
+    ):
+        def wrapper(wrapped, instance, args, kwargs):
+            return func(tracer, client, to_wrap, wrapped, instance, args, kwargs)
+
+        return wrapper
+
+    return _with_tracer_and_client
+
+
+def retry_sync(func, retries=5, delay=0.5, error_message="Operation failed"):
+    """Utility function for retry logic in synchronous operations"""
+    for attempt in range(retries):
+        try:
+            result = func()
+            if result:  # If function returns truthy value, consider it successful
+                return result
+            if attempt == retries - 1:  # Last attempt
+                logger.debug(f"{error_message} after all retries")
+                return None
+        except Exception as e:
+            if attempt == retries - 1:  # Last attempt
+                logger.error(f"{error_message}: {e}")
+                return None
+        time.sleep(delay)
+    return None
+
+
+async def retry_async(func, retries=5, delay=0.5, error_message="Operation failed"):
+    """Utility function for retry logic in asynchronous operations"""
+    for attempt in range(retries):
+        try:
+            result = await func()
+            if result:  # If function returns truthy value, consider it successful
+                return result
+            if attempt == retries - 1:  # Last attempt
+                logger.error(f"{error_message} after all retries")
+                return None
+        except Exception as e:
+            if attempt == retries - 1:  # Last attempt
+                logger.error(f"{error_message}: {e}")
+                return None
+        await asyncio.sleep(delay)
+    return None

lmnr/sdk/client/asynchronous/async_client.py

@@ -0,0 +1,180 @@
+"""
+Laminar HTTP client. Used to send data to/from the Laminar API.
+"""
+
+import httpx
+import re
+from typing import TypeVar
+from types import TracebackType
+
+from lmnr.sdk.client.asynchronous.resources import (
+    AsyncBrowserEvents,
+    AsyncEvals,
+    AsyncTags,
+    AsyncEvaluators,
+)
+from lmnr.sdk.client.asynchronous.resources.datasets import AsyncDatasets
+from lmnr.sdk.utils import from_env
+
+_T = TypeVar("_T", bound="AsyncLaminarClient")
+
+
+class AsyncLaminarClient:
+    __base_url: str
+    __project_api_key: str
+    __client: httpx.AsyncClient = None
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        project_api_key: str | None = None,
+        port: int | None = None,
+        timeout: int = 3600,
+    ):
+        """Initializer for the Laminar HTTP client.
+
+        Args:
+            base_url (str | None): base URL of the Laminar API. If not
+                provided, the LMNR_BASE_URL environment variable is used or we
+                default to "https://api.lmnr.ai".
+            project_api_key (str | None): Laminar project API key. If not
+                provided, the LMNR_PROJECT_API_KEY environment variable is used.
+            port (int | None, optional): port of the Laminar API HTTP server.\
+                Overrides any port in the base URL.
+                Defaults to None. If none is provided, the default port (443) will
+                be used.
+            timeout (int, optional): global timeout seconds for the HTTP client.\
+                Applied to all httpx operations, i.e. connect, read, get_from_pool, etc.
+                Defaults to 3600.
+        """
+        # If port is already in the base URL, use it as is
+        base_url = base_url or from_env("LMNR_BASE_URL") or "https://api.lmnr.ai"
+        if match := re.search(r":(\d{1,5})$", base_url):
+            base_url = base_url[: -len(match.group(0))]
+            if port is None:
+                port = int(match.group(1))
+
+        base_url = base_url.rstrip("/")
+        self.__base_url = f"{base_url}:{port or 443}"
+        self.__project_api_key = project_api_key or from_env("LMNR_PROJECT_API_KEY")
+        if not self.__project_api_key:
+            raise ValueError(
+                "Project API key is not set. Please set the LMNR_PROJECT_API_KEY environment "
+                "variable or pass project_api_key to the initializer."
+            )
+
+        self.__client = httpx.AsyncClient(
+            headers=self._headers(),
+            timeout=timeout,
+            # Context: If the server responds with a 413, the connection becomes
+            # poisoned and freezes on subsequent requests, and there is no way
+            # to recover or recycle such connection.
+            # Setting max_keepalive_connections to 0 will resolve this, but is
+            # less efficient, as it will create a new connection
+            # (not client, so still better) for each request.
+            #
+            # Note: from my experiments with a simple python server, forcing the
+            # server to read/consume the request payload from the socket seems
+            # to resolve this, but I haven't figured out how to do that in our
+            # real actix-web backend server and whether it makes sense to do so.
+            #
+            # TODO: investigate if there are better ways to fix this rather than
+            # setting keepalive_expiry to 0. Other alternative: migrate to
+            # requests + aiohttp.
+            #
+            # limits=httpx.Limits(
+            #     max_keepalive_connections=0,
+            #     keepalive_expiry=0,
+            # ),
+        )
+
+        # Initialize resource objects
+        self.__evals = AsyncEvals(
+            self.__client, self.__base_url, self.__project_api_key
+        )
+        self.__evaluators = AsyncEvaluators(
+            self.__client, self.__base_url, self.__project_api_key
+        )
+        self.__browser_events = AsyncBrowserEvents(
+            self.__client, self.__base_url, self.__project_api_key
+        )
+        self.__tags = AsyncTags(self.__client, self.__base_url, self.__project_api_key)
+        self.__datasets = AsyncDatasets(
+            self.__client, self.__base_url, self.__project_api_key
+        )
+
+    @property
+    def evals(self) -> AsyncEvals:
+        """Get the Evals resource.
+
+        Returns:
+            AsyncEvals: The Evals resource instance.
+        """
+        return self.__evals
+
+    @property
+    def _browser_events(self) -> AsyncBrowserEvents:
+        """Get the BrowserEvents resource.
+
+        Returns:
+            AsyncBrowserEvents: The BrowserEvents resource instance.
+        """
+        return self.__browser_events
+
+    @property
+    def tags(self) -> AsyncTags:
+        """Get the Tags resource.
+
+        Returns:
+            AsyncTags: The Tags resource instance.
+        """
+        return self.__tags
+
+    @property
+    def evaluators(self) -> AsyncEvaluators:
+        """Get the Evaluators resource.
+
+        Returns:
+            AsyncEvaluators: The Evaluators resource instance.
+        """
+        return self.__evaluators
+
+    @property
+    def datasets(self) -> AsyncDatasets:
+        """Get the Datasets resource.
+
+        Returns:
+            AsyncDatasets: The Datasets resource instance.
+        """
+        return self.__datasets
+
+    @property
+    def is_closed(self) -> bool:
+        return self.__client.is_closed
+
+    async def close(self) -> None:
+        """Close the underlying HTTPX client.
+
+        The client will *not* be usable after this.
+        """
+        if hasattr(self, "__client"):
+            await self.__client.aclose()
+
+    async def __aenter__(self: _T) -> _T:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    def _headers(self) -> dict[str, str]:
+        assert self.__project_api_key is not None, "Project API key is not set"
+        return {
+            "Authorization": "Bearer " + self.__project_api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }

lmnr/sdk/client/asynchronous/resources/__init__.py

@@ -0,0 +1,6 @@
+from lmnr.sdk.client.asynchronous.resources.browser_events import AsyncBrowserEvents
+from lmnr.sdk.client.asynchronous.resources.evals import AsyncEvals
+from lmnr.sdk.client.asynchronous.resources.tags import AsyncTags
+from lmnr.sdk.client.asynchronous.resources.evaluators import AsyncEvaluators
+
+__all__ = ["AsyncEvals", "AsyncBrowserEvents", "AsyncTags", "AsyncEvaluators"]

lmnr/sdk/client/asynchronous/resources/base.py

@@ -0,0 +1,32 @@
+"""Base class for resource objects."""
+
+import httpx
+
+
+class BaseAsyncResource:
+    """Base class for all API resources."""
+
+    def __init__(self, client: httpx.AsyncClient, base_url: str, project_api_key: str):
+        """Initialize the resource.
+
+        Args:
+            client (httpx.AsyncClient): HTTP client instance
+            base_url (str): Base URL for the API
+            project_api_key (str): Project API key
+        """
+        self._client = client
+        self._base_url = base_url
+        self._project_api_key = project_api_key
+
+    def _headers(self) -> dict[str, str]:
+        """Generate request headers with authentication.
+
+        Returns:
+            dict[str, str]: Headers dictionary
+        """
+        assert self._project_api_key is not None, "Project API key is not set"
+        return {
+            "Authorization": "Bearer " + self._project_api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }

lmnr/sdk/client/asynchronous/resources/browser_events.py

@@ -0,0 +1,41 @@
+"""Resource for sending browser events."""
+
+import gzip
+import json
+
+from lmnr.sdk.client.asynchronous.resources.base import BaseAsyncResource
+
+from lmnr.version import PYTHON_VERSION, __version__
+
+
+class AsyncBrowserEvents(BaseAsyncResource):
+    """Resource for sending browser events."""
+
+    async def send(
+        self,
+        session_id: str,
+        trace_id: str,
+        events: list[dict],
+    ):
+        url = self._base_url + "/v1/browser-sessions/events"
+        payload = {
+            "sessionId": session_id,
+            "traceId": trace_id,
+            "events": events,
+            "source": f"python@{PYTHON_VERSION}",
+            "sdkVersion": __version__,
+        }
+
+        compressed_payload = gzip.compress(json.dumps(payload).encode("utf-8"))
+        response = await self._client.post(
+            url,
+            content=compressed_payload,
+            headers={
+                **self._headers(),
+                "Content-Encoding": "gzip",
+            },
+        )
+        if response.status_code != 200:
+            raise ValueError(
+                f"Failed to send events: [{response.status_code}] {response.text}"
+            )

lmnr/sdk/client/asynchronous/resources/datasets.py

@@ -0,0 +1,131 @@
+"""Datasets resource for interacting with Laminar datasets API."""
+
+import math
+import uuid
+
+from lmnr.sdk.client.asynchronous.resources.base import BaseAsyncResource
+from lmnr.sdk.log import get_default_logger
+from lmnr.sdk.types import (
+    Datapoint,
+    Dataset,
+    GetDatapointsResponse,
+    PushDatapointsResponse,
+)
+from lmnr.sdk.utils import serialize
+
+logger = get_default_logger(__name__)
+
+DEFAULT_DATASET_PULL_LIMIT = 100
+DEFAULT_DATASET_PUSH_BATCH_SIZE = 100
+
+
+class AsyncDatasets(BaseAsyncResource):
+    """Resource for interacting with Laminar datasets API."""
+
+    async def list_datasets(self) -> list[Dataset]:
+        """List all datasets."""
+        response = await self._client.get(
+            f"{self._base_url}/v1/datasets",
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise ValueError(
+                f"Error listing datasets: [{response.status_code}] {response.text}"
+            )
+        return [Dataset.model_validate(dataset) for dataset in response.json()]
+
+    async def get_dataset_by_name(self, name: str) -> list[Dataset]:
+        """Get a dataset by name."""
+        response = await self._client.get(
+            f"{self._base_url}/v1/datasets",
+            params={"name": name},
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise ValueError(
+                f"Error getting dataset: [{response.status_code}] {response.text}"
+            )
+        return [Dataset.model_validate(dataset) for dataset in response.json()]
+
+    async def push(
+        self,
+        points: list[Datapoint],
+        name: str | None = None,
+        id: uuid.UUID | None = None,
+        batch_size: int = DEFAULT_DATASET_PUSH_BATCH_SIZE,
+        create_dataset: bool = False,
+    ) -> PushDatapointsResponse | None:
+        """Push data to a dataset."""
+
+        if name is None and id is None:
+            raise ValueError("Either name or id must be provided")
+
+        if name is not None and id is not None:
+            raise ValueError("Only one of name or id must be provided")
+
+        if create_dataset and name is None:
+            raise ValueError("Name must be provided when creating a new dataset")
+
+        identifier = {"name": name} if name is not None else {"datasetId": id}
+
+        batch_num = 0
+        total_batches = math.ceil(len(points) / batch_size)
+        response = None
+        for i in range(0, len(points), batch_size):
+            batch_num += 1
+            logger.debug(f"Pushing batch {batch_num} of {total_batches}")
+            batch = points[i : i + batch_size]
+            response = await self._client.post(
+                f"{self._base_url}/v1/datasets/datapoints",
+                json={
+                    **identifier,
+                    "datapoints": [serialize(point) for point in batch],
+                    "createDataset": create_dataset,
+                },
+                headers=self._headers(),
+            )
+
+            # 201 when creating a new dataset
+            if response.status_code not in [200, 201]:
+                raise ValueError(
+                    f"Error pushing data to dataset: [{response.status_code}] {response.text}"
+                )
+
+            response = PushDatapointsResponse.model_validate(response.json())
+        # Currently, the response only contains the dataset ID,
+        # so it's safe to return the last response only.
+        return response
+
+    async def pull(
+        self,
+        name: str | None = None,
+        id: uuid.UUID | None = None,
+        # TODO: move const to one file, import in CLI
+        limit: int = DEFAULT_DATASET_PULL_LIMIT,
+        offset: int = 0,
+    ) -> GetDatapointsResponse:
+        """Pull data from a dataset."""
+
+        if name is None and id is None:
+            raise ValueError("Either name or id must be provided")
+
+        if name is not None and id is not None:
+            raise ValueError("Only one of name or id must be provided")
+
+        identifier = {"name": name} if name is not None else {"datasetId": id}
+
+        params = {
+            **identifier,
+            "offset": offset,
+            "limit": limit,
+        }
+        response = await self._client.get(
+            f"{self._base_url}/v1/datasets/datapoints",
+            params=params,
+            headers=self._headers(),
+        )
+        if response.status_code != 200:
+            raise ValueError(
+                f"Error pulling data from dataset: [{response.status_code}] {response.text}"
+            )
+        return GetDatapointsResponse.model_validate(response.json())