lmnr 0.6.3__py3-none-any.whl → 0.6.4__py3-none-any.whl

lmnr/sdk/browser/utils.py

@@ -1,7 +1,6 @@
 import asyncio
 import logging
 import time
-from typing import Union
 
 from lmnr.sdk.client.asynchronous.async_client import AsyncLaminarClient
 from lmnr.sdk.client.synchronous.sync_client import LaminarClient
@@ -24,13 +23,15 @@ def with_tracer_wrapper(func):
 def with_tracer_and_client_wrapper(func):
     """Helper for providing tracer and client for wrapper functions."""
 
-    def _with_tracer(tracer, client: Union[LaminarClient, AsyncLaminarClient], to_wrap):
+    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
+    return _with_tracer_and_client
 
 
 def retry_sync(func, retries=5, delay=0.5, error_message="Operation failed"):

lmnr/sdk/client/asynchronous/async_client.py

@@ -4,13 +4,14 @@ Laminar HTTP client. Used to send data to/from the Laminar API.
 
 import httpx
 import re
-from typing import Optional, TypeVar
+from typing import TypeVar
 from types import TracebackType
 
 from lmnr.sdk.client.asynchronous.resources import (
     AsyncAgent,
     AsyncBrowserEvents,
     AsyncEvals,
+    AsyncTags,
 )
 from lmnr.sdk.utils import from_env
 
@@ -24,17 +25,20 @@ class AsyncLaminarClient:
 
     def __init__(
         self,
-        base_url: Optional[str] = None,
-        project_api_key: Optional[str] = None,
-        port: Optional[int] = None,
+        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): base URL of the Laminar API.
-            project_api_key (str): Laminar project API key
-            port (Optional[int], optional): port of the Laminar API HTTP server.\
+            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.
@@ -73,6 +77,7 @@ class AsyncLaminarClient:
         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)
 
     @property
     def agent(self) -> AsyncAgent:
@@ -101,6 +106,15 @@ class AsyncLaminarClient:
         """
         return self.__browser_events
 
+    @property
+    def tags(self) -> AsyncTags:
+        """Get the Tags resource.
+
+        Returns:
+            AsyncTags: The Tags resource instance.
+        """
+        return self.__tags
+
     def is_closed(self) -> bool:
         return self.__client.is_closed
 
@@ -109,16 +123,17 @@ class AsyncLaminarClient:
 
         The client will *not* be usable after this.
         """
-        await self.__client.aclose()
+        if hasattr(self, "__client"):
+            await self.__client.aclose()
 
     async def __aenter__(self: _T) -> _T:
         return self
 
     async def __aexit__(
         self,
-        exc_type: Optional[type[BaseException]],
-        exc: Optional[BaseException],
-        exc_tb: Optional[TracebackType],
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        exc_tb: TracebackType | None,
     ) -> None:
         await self.close()
 

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

@@ -1,9 +1,11 @@
 from lmnr.sdk.client.asynchronous.resources.agent import AsyncAgent
 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
 
 __all__ = [
     "AsyncAgent",
     "AsyncEvals",
     "AsyncBrowserEvents",
+    "AsyncTags",
 ]

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

@@ -5,8 +5,6 @@ from typing import (
     AsyncIterator,
     Awaitable,
     Literal,
-    Optional,
-    Union,
     overload,
 )
 import uuid
@@ -31,44 +29,44 @@ class AsyncAgent(BaseAsyncResource):
         self,
         prompt: str,
         stream: Literal[True],
-        parent_span_context: Optional[Union[LaminarSpanContext, str]] = None,
-        model_provider: Optional[ModelProvider] = None,
-        model: Optional[str] = None,
+        parent_span_context: LaminarSpanContext | str | None = None,
+        model_provider: ModelProvider | None = None,
+        model: str | None = None,
         enable_thinking: bool = True,
-        agent_state: Optional[str] = None,
-        storage_state: Optional[str] = None,
+        agent_state: str | None = None,
+        storage_state: str | None = None,
         return_screenshots: bool = False,
         return_agent_state: bool = False,
         return_storage_state: bool = False,
         disable_give_control: bool = False,
-        timeout: Optional[int] = None,
-        cdp_url: Optional[str] = None,
-        max_steps: Optional[int] = None,
-        thinking_token_budget: Optional[int] = None,
-        start_url: Optional[str] = None,
-        user_agent: Optional[str] = None,
+        timeout: int | None = None,
+        cdp_url: str | None = None,
+        max_steps: int | None = None,
+        thinking_token_budget: int | None = None,
+        start_url: str | None = None,
+        user_agent: str | None = None,
     ) -> AsyncIterator[RunAgentResponseChunk]:
         """Run Laminar index agent in streaming mode.
 
         Args:
             prompt (str): prompt for the agent
             stream (Literal[True]): whether to stream the agent's response
-            parent_span_context (Optional[Union[LaminarSpanContext, str]], optional): span context if the agent is part of a trace
-            model_provider (Optional[ModelProvider], optional): LLM model provider
-            model (Optional[str], optional): LLM model name
+            parent_span_context (LaminarSpanContext | str | None, optional): span context if the agent is part of a trace
+            model_provider (ModelProvider | None, optional): LLM model provider
+            model (str | None, optional): LLM model name
             enable_thinking (bool, optional): whether to enable thinking on the underlying LLM. Default to True.
-            agent_state (Optional[str], optional): the agent's state as returned by the previous agent run. Default to None.
-            storage_state (Optional[str], optional): the browser's storage state as returned by the previous agent run. Default to None.
+            agent_state (str | None, optional): the agent's state as returned by the previous agent run. Default to None.
+            storage_state (str | None, optional): the browser's storage state as returned by the previous agent run. Default to None.
             return_screenshots (bool, optional): whether to return screenshots of the agent's states at every step. Default to False.
             return_agent_state (bool, optional): whether to return the agent's state in the final chunk. Default to False.
             return_storage_state (bool, optional): whether to return the storage state in the final chunk. Default to False.
             disable_give_control (bool, optional): whether to NOT give the agent additional direction to give control to the user for tasks such as login. Default to False.
-            timeout (Optional[int], optional): timeout seconds for the agent's response. Default to None.
-            cdp_url (Optional[str], optional): Chrome DevTools Protocol URL of an existing browser session. Default to None.
-            max_steps (Optional[int], optional): maximum number of steps the agent can take. If not set, the backend will use a default value (currently 100). Default to None.
-            thinking_token_budget (Optional[int], optional): maximum number of tokens the underlying LLM can spend on thinking in each step, if supported by the model. Default to None.
-            start_url (Optional[str], optional): the URL to start the agent on. Must be a valid URL - refer to https://playwright.dev/docs/api/class-page#page-goto. If not specified, the agent infers this from the prompt. Default to None.
-            user_agent (Optional[str], optional): the user to be sent to the browser. If not specified, Laminar uses the default user agent. Default to None.
+            timeout (int | None, optional): timeout seconds for the agent's response. Default to None.
+            cdp_url (str | None, optional): Chrome DevTools Protocol URL of an existing browser session. Default to None.
+            max_steps (int | None, optional): maximum number of steps the agent can take. If not set, the backend will use a default value (currently 100). Default to None.
+            thinking_token_budget (int | None, optional): maximum number of tokens the underlying LLM can spend on thinking in each step, if supported by the model. Default to None.
+            start_url (str | None, optional): the URL to start the agent on. Must be a valid URL - refer to https://playwright.dev/docs/api/class-page#page-goto. If not specified, the agent infers this from the prompt. Default to None.
+            user_agent (str | None, optional): the user to be sent to the browser. If not specified, Laminar uses the default user agent. Default to None.
 
         Returns:
             AsyncIterator[RunAgentResponseChunk]: a generator of response chunks
@@ -79,43 +77,43 @@ class AsyncAgent(BaseAsyncResource):
     async def run(
         self,
         prompt: str,
-        parent_span_context: Optional[Union[LaminarSpanContext, str]] = None,
-        model_provider: Optional[ModelProvider] = None,
-        model: Optional[str] = None,
+        parent_span_context: LaminarSpanContext | str | None = None,
+        model_provider: ModelProvider | None = None,
+        model: str | None = None,
         enable_thinking: bool = True,
-        agent_state: Optional[str] = None,
-        storage_state: Optional[str] = None,
+        agent_state: str | None = None,
+        storage_state: str | None = None,
         return_screenshots: bool = False,
         return_agent_state: bool = False,
         return_storage_state: bool = False,
         disable_give_control: bool = False,
-        timeout: Optional[int] = None,
-        cdp_url: Optional[str] = None,
-        max_steps: Optional[int] = None,
-        thinking_token_budget: Optional[int] = None,
-        start_url: Optional[str] = None,
-        user_agent: Optional[str] = None,
+        timeout: int | None = None,
+        cdp_url: str | None = None,
+        max_steps: int | None = None,
+        thinking_token_budget: int | None = None,
+        start_url: str | None = None,
+        user_agent: str | None = None,
     ) -> AgentOutput:
         """Run Laminar index agent.
 
         Args:
             prompt (str): prompt for the agent
-            parent_span_context (Optional[LaminarSpanContext], optional): span context if the agent is part of a trace
-            model_provider (Optional[ModelProvider], optional): LLM model provider
-            model (Optional[str], optional): LLM model name
+            parent_span_context (LaminarSpanContext | str | None, optional): span context if the agent is part of a trace
+            model_provider (ModelProvider | None, optional): LLM model provider
+            model (str | None, optional): LLM model name
             enable_thinking (bool, optional): whether to enable thinking on the underlying LLM. Default to True.
-            agent_state (Optional[str], optional): the agent's state as returned by the previous agent run. Default to None.
-            storage_state (Optional[str], optional): the browser's storage state as returned by the previous agent run. Default to None.
+            agent_state (str | None, optional): the agent's state as returned by the previous agent run. Default to None.
+            storage_state (str | None, optional): the browser's storage state as returned by the previous agent run. Default to None.
             return_screenshots (bool, optional): whether to return screenshots of the agent's states at every step. Default to False.
             return_agent_state (bool, optional): whether to return the agent's state. Default to False.
             return_storage_state (bool, optional): whether to return the storage state. Default to False.
             disable_give_control (bool, optional): whether to NOT give the agent additional direction to give control to the user for tasks such as login. Default to False.
-            timeout (Optional[int], optional): timeout seconds for the agent's response. Default to None.
-            cdp_url (Optional[str], optional): Chrome DevTools Protocol URL of an existing browser session. Default to None.
-            max_steps (Optional[int], optional): maximum number of steps the agent can take. If not set, the backend will use a default value (currently 100). Default to None.
-            thinking_token_budget (Optional[int], optional): maximum number of tokens the underlying LLM can spend on thinking in each step, if supported by the model. Default to None.
-            start_url (Optional[str], optional): the URL to start the agent on. Must be a valid URL - refer to https://playwright.dev/docs/api/class-page#page-goto. If not specified, the agent infers this from the prompt. Default to None.
-            user_agent (Optional[str], optional): the user to be sent to the browser. If not specified, Laminar uses the default user agent. Default to None.
+            timeout (int | None, optional): timeout seconds for the agent's response. Default to None.
+            cdp_url (str | None, optional): Chrome DevTools Protocol URL of an existing browser session. Default to None.
+            max_steps (int | None, optional): maximum number of steps the agent can take. If not set, the backend will use a default value (currently 100). Default to None.
+            thinking_token_budget (int | None, optional): maximum number of tokens the underlying LLM can spend on thinking in each step, if supported by the model. Default to None.
+            start_url (str | None, optional): the URL to start the agent on. Must be a valid URL - refer to https://playwright.dev/docs/api/class-page#page-goto. If not specified, the agent infers this from the prompt. Default to None.
+            user_agent (str | None, optional): the user to be sent to the browser. If not specified, Laminar uses the default user agent. Default to None.
 
         Returns:
             AgentOutput: agent output
@@ -126,44 +124,44 @@ class AsyncAgent(BaseAsyncResource):
     async def run(
         self,
         prompt: str,
-        parent_span_context: Optional[Union[LaminarSpanContext, str]] = None,
-        model_provider: Optional[ModelProvider] = None,
-        model: Optional[str] = None,
+        parent_span_context: LaminarSpanContext | str | None = None,
+        model_provider: ModelProvider | None = None,
+        model: str | None = None,
         stream: Literal[False] = False,
         enable_thinking: bool = True,
-        agent_state: Optional[str] = None,
-        storage_state: Optional[str] = None,
+        agent_state: str | None = None,
+        storage_state: str | None = None,
         return_screenshots: bool = False,
         return_agent_state: bool = False,
         return_storage_state: bool = False,
         disable_give_control: bool = False,
-        timeout: Optional[int] = None,
-        max_steps: Optional[int] = None,
-        thinking_token_budget: Optional[int] = None,
-        start_url: Optional[str] = None,
-        user_agent: Optional[str] = None,
+        timeout: int | None = None,
+        max_steps: int | None = None,
+        thinking_token_budget: int | None = None,
+        start_url: str | None = None,
+        user_agent: str | None = None,
     ) -> AgentOutput:
         """Run Laminar index agent.
 
         Args:
             prompt (str): prompt for the agent
-            parent_span_context (Optional[Union[LaminarSpanContext, str]], optional): span context if the agent is part of a trace
-            model_provider (Optional[ModelProvider], optional): LLM model provider
-            model (Optional[str], optional): LLM model name
+            parent_span_context (LaminarSpanContext | str | None, optional): span context if the agent is part of a trace
+            model_provider (ModelProvider | None, optional): LLM model provider
+            model (str | None, optional): LLM model name
             stream (Literal[False], optional): whether to stream the agent's response
             enable_thinking (bool, optional): whether to enable thinking on the underlying LLM. Default to True.
-            agent_state (Optional[str], optional): the agent's state as returned by the previous agent run. Default to None.
-            storage_state (Optional[str], optional): the browser's storage state as returned by the previous agent run. Default to None.
+            agent_state (str | None, optional): the agent's state as returned by the previous agent run. Default to None.
+            storage_state (str | None, optional): the browser's storage state as returned by the previous agent run. Default to None.
             return_screenshots (bool, optional): whether to return screenshots of the agent's states at every step. Default to False.
             return_agent_state (bool, optional): whether to return the agent's state. Default to False.
             return_storage_state (bool, optional): whether to return the storage state. Default to False.
             disable_give_control (bool, optional): whether to NOT give the agent additional direction to give control to the user for tasks such as login. Default to False.
-            timeout (Optional[int], optional): timeout seconds for the agent's response. Default to None.
-            cdp_url (Optional[str], optional): Chrome DevTools Protocol URL of an existing browser session. Default to None.
-            max_steps (Optional[int], optional): maximum number of steps the agent can take. If not set, the backend will use a default value (currently 100). Default to None.
-            thinking_token_budget (Optional[int], optional): maximum number of tokens the underlying LLM can spend on thinking in each step, if supported by the model. Default to None.
-            start_url (Optional[str], optional): the URL to start the agent on. Must be a valid URL - refer to https://playwright.dev/docs/api/class-page#page-goto. If not specified, the agent infers this from the prompt. Default to None.
-            user_agent (Optional[str], optional): the user to be sent to the browser. If not specified, Laminar uses the default user agent. Default to None.
+            timeout (int | None, optional): timeout seconds for the agent's response. Default to None.
+            cdp_url (str | None, optional): Chrome DevTools Protocol URL of an existing browser session. Default to None.
+            max_steps (int | None, optional): maximum number of steps the agent can take. If not set, the backend will use a default value (currently 100). Default to None.
+            thinking_token_budget (int | None, optional): maximum number of tokens the underlying LLM can spend on thinking in each step, if supported by the model. Default to None.
+            start_url (str | None, optional): the URL to start the agent on. Must be a valid URL - refer to https://playwright.dev/docs/api/class-page#page-goto. If not specified, the agent infers this from the prompt. Default to None.
+            user_agent (str | None, optional): the user to be sent to the browser. If not specified, Laminar uses the default user agent. Default to None.
 
         Returns:
             AgentOutput: agent output
@@ -173,48 +171,48 @@ class AsyncAgent(BaseAsyncResource):
     async def run(
         self,
         prompt: str,
-        parent_span_context: Optional[Union[LaminarSpanContext, str]] = None,
-        model_provider: Optional[ModelProvider] = None,
-        model: Optional[str] = None,
+        parent_span_context: LaminarSpanContext | str | None = None,
+        model_provider: ModelProvider | None = None,
+        model: str | None = None,
         stream: bool = False,
         enable_thinking: bool = True,
-        agent_state: Optional[str] = None,
-        storage_state: Optional[str] = None,
+        agent_state: str | None = None,
+        storage_state: str | None = None,
         return_screenshots: bool = False,
         return_agent_state: bool = False,
         return_storage_state: bool = False,
         disable_give_control: bool = False,
-        timeout: Optional[int] = None,
-        cdp_url: Optional[str] = None,
-        max_steps: Optional[int] = None,
-        thinking_token_budget: Optional[int] = None,
-        start_url: Optional[str] = None,
-        user_agent: Optional[str] = None,
-    ) -> Union[AgentOutput, Awaitable[AsyncIterator[RunAgentResponseChunk]]]:
+        timeout: int | None = None,
+        cdp_url: str | None = None,
+        max_steps: int | None = None,
+        thinking_token_budget: int | None = None,
+        start_url: str | None = None,
+        user_agent: str | None = None,
+    ) -> AgentOutput | Awaitable[AsyncIterator[RunAgentResponseChunk]]:
         """Run Laminar index agent.
 
         Args:
             prompt (str): prompt for the agent
-            parent_span_context (Optional[Union[LaminarSpanContext, str]], optional): span context if the agent is part of a trace
-            model_provider (Optional[ModelProvider], optional): LLM model provider
-            model (Optional[str], optional): LLM model name
+            parent_span_context (LaminarSpanContext | str | None, optional): span context if the agent is part of a trace
+            model_provider (ModelProvider | None, optional): LLM model provider
+            model (str | None, optional): LLM model name
             stream (bool, optional): whether to stream the agent's response
             enable_thinking (bool, optional): whether to enable thinking on the underlying LLM. Default to True.
-            agent_state (Optional[str], optional): the agent's state as returned by the previous agent run. Default to None.
-            storage_state (Optional[str], optional): the browser's storage state as returned by the previous agent run. Default to None.
+            agent_state (str | None, optional): the agent's state as returned by the previous agent run. Default to None.
+            storage_state (str | None, optional): the browser's storage state as returned by the previous agent run. Default to None.
             return_screenshots (bool, optional): whether to return screenshots of the agent's states at every step. Default to False.
             return_agent_state (bool, optional): whether to return the agent's state. Default to False.
             return_storage_state (bool, optional): whether to return the storage state. Default to False.
             disable_give_control (bool, optional): whether to NOT give the agent additional direction to give control to the user for tasks such as login. Default to False.
-            timeout (Optional[int], optional): timeout seconds for the agent's response. Default to None.
-            cdp_url (Optional[str], optional): Chrome DevTools Protocol URL of an existing browser session. Default to None.
-            max_steps (Optional[int], optional): maximum number of steps the agent can take. If not set, the backend will use a default value (currently 100). Default to None.
-            thinking_token_budget (Optional[int], optional): maximum number of tokens the underlying LLM can spend on thinking in each step, if supported by the model. Default to None.
-            start_url (Optional[str], optional): the URL to start the agent on. Must be a valid URL - refer to https://playwright.dev/docs/api/class-page#page-goto. If not specified, the agent infers this from the prompt. Default to None.
-            user_agent (Optional[str], optional): the user to be sent to the browser. If not specified, Laminar uses the default user agent. Default to None.
+            timeout (int | None, optional): timeout seconds for the agent's response. Default to None.
+            cdp_url (str | None, optional): Chrome DevTools Protocol URL of an existing browser session. Default to None.
+            max_steps (int | None, optional): maximum number of steps the agent can take. If not set, the backend will use a default value (currently 100). Default to None.
+            thinking_token_budget (int | None, optional): maximum number of tokens the underlying LLM can spend on thinking in each step, if supported by the model. Default to None.
+            start_url (str | None, optional): the URL to start the agent on. Must be a valid URL - refer to https://playwright.dev/docs/api/class-page#page-goto. If not specified, the agent infers this from the prompt. Default to None.
+
 
         Returns:
-            Union[AgentOutput, AsyncIterator[RunAgentResponseChunk]]: agent output or a generator of response chunks
+            AgentOutput | AsyncIterator[RunAgentResponseChunk]: agent output or a generator of response chunks
         """
         if parent_span_context is None:
             span = trace.get_current_span()

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

@@ -1,7 +1,6 @@
 """Evals resource for interacting with Laminar evaluations API."""
 
 import uuid
-from typing import Optional, Union
 
 from lmnr.sdk.client.asynchronous.resources.base import BaseAsyncResource
 from lmnr.sdk.types import (
@@ -15,13 +14,13 @@ class AsyncEvals(BaseAsyncResource):
     """Resource for interacting with Laminar evaluations API."""
 
     async def init(
-        self, name: Optional[str] = None, group_name: Optional[str] = None
+        self, name: str | None = None, group_name: str | None = None
     ) -> InitEvaluationResponse:
         """Initialize a new evaluation.
 
         Args:
-            name (Optional[str], optional): Name of the evaluation. Defaults to None.
-            group_name (Optional[str], optional): Group name for the evaluation. Defaults to None.
+            name (str | None, optional): Name of the evaluation. Defaults to None.
+            group_name (str | None, optional): Group name for the evaluation. Defaults to None.
 
         Returns:
             InitEvaluationResponse: The response from the initialization request.
@@ -40,15 +39,15 @@ class AsyncEvals(BaseAsyncResource):
     async def save_datapoints(
         self,
         eval_id: uuid.UUID,
-        datapoints: list[Union[EvaluationResultDatapoint, PartialEvaluationDatapoint]],
-        group_name: Optional[str] = None,
+        datapoints: list[EvaluationResultDatapoint | PartialEvaluationDatapoint],
+        group_name: str | None = None,
     ):
         """Save evaluation datapoints.
 
         Args:
             eval_id (uuid.UUID): The evaluation ID.
-            datapoints (list[Union[EvaluationResultDatapoint, PartialEvaluationDatapoint]]): The datapoints to save.
-            group_name (Optional[str], optional): Group name for the datapoints. Defaults to None.
+            datapoints (list[EvaluationResultDatapoint | PartialEvaluationDatapoint]): The datapoints to save.
+            group_name (str | None, optional): Group name for the datapoints. Defaults to None.
 
         Raises:
             ValueError: If there's an error saving the datapoints.

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

@@ -0,0 +1,89 @@
+"""Resource for tagging traces."""
+
+import json
+import uuid
+
+from lmnr.sdk.client.asynchronous.resources.base import BaseAsyncResource
+from lmnr.sdk.log import get_default_logger
+
+logger = get_default_logger(__name__)
+
+
+class AsyncTags(BaseAsyncResource):
+    """Resource for tagging traces."""
+
+    async def tag(
+        self,
+        trace_id: str | int | uuid.UUID,
+        tags: list[str] | str,
+    ):
+        """Tag a trace with a list of tags. Note that the trace must be ended
+        before tagging it. You may want to call `Laminar.flush()` after the
+        trace that you want to tag.
+
+        Args:
+            trace_id (str | int | uuid.UUID): The trace id to tag.
+            tags (list[str] | str): The tag or list of tags to add to the trace.
+
+        Raises:
+            ValueError: If the trace id is not a valid UUID.
+
+        Returns:
+            list[dict]: The response from the server.
+
+        Example:
+        ```python
+        from lmnr import Laminar, AsyncLaminarClient, observe
+
+        Laminar.initialize()
+        client = AsyncLaminarClient()
+        trace_id = None
+
+        @observe()
+        def foo():
+            trace_id = Laminar.get_trace_id()
+            pass
+
+        # make sure `foo` is called outside a trace context
+        foo()
+
+        # or make sure the trace is ended by this point
+        Laminar.flush()
+
+        await client.tags.tag(trace_id, "my_tag")
+        ```
+        """
+        trace_tags = tags if isinstance(tags, list) else [tags]
+        if isinstance(trace_id, uuid.UUID):
+            trace_id = str(trace_id)
+        elif isinstance(trace_id, int):
+            trace_id = str(uuid.UUID(int=trace_id))
+        elif isinstance(trace_id, str):
+            uuid.UUID(trace_id)  # Will raise ValueError if invalid
+        else:
+            raise ValueError(f"Invalid trace id: {trace_id}")
+
+        url = self._base_url + "/v1/tag"
+        payload = {
+            "traceId": trace_id,
+            "names": trace_tags,
+        }
+        response = await self._client.post(
+            url,
+            content=json.dumps(payload),
+            headers={
+                **self._headers(),
+            },
+        )
+
+        if response.status_code == 404:
+            logger.warning(
+                f"Trace {trace_id} not found. The trace may have not been ended yet."
+            )
+            return []
+
+        if response.status_code != 200:
+            raise ValueError(
+                f"Failed to tag trace: [{response.status_code}] {response.text}"
+            )
+        return response.json()

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

@@ -1,5 +1,6 @@
 from lmnr.sdk.client.synchronous.resources.agent import Agent
 from lmnr.sdk.client.synchronous.resources.browser_events import BrowserEvents
 from lmnr.sdk.client.synchronous.resources.evals import Evals
+from lmnr.sdk.client.synchronous.resources.tags import Tags
 
-__all__ = ["Agent", "Evals", "BrowserEvents"]
+__all__ = ["Agent", "Evals", "BrowserEvents", "Tags"]