braintrust 0.3.15__py3-none-any.whl → 0.4.0__py3-none-any.whl

braintrust/logger.py

@@ -19,24 +19,16 @@ import traceback
 import types
 import uuid
 from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterator, Mapping, MutableMapping, Sequence
 from functools import partial, wraps
 from multiprocessing import cpu_count
 from types import TracebackType
 from typing import (
     Any,
-    Callable,
     Dict,
     Generic,
-    Iterator,
-    List,
     Literal,
-    Mapping,
-    MutableMapping,
     Optional,
-    Sequence,
-    Set,
-    Tuple,
-    Type,
     TypedDict,
     TypeVar,
     Union,
@@ -107,7 +99,7 @@ from .util import (
 REDACTION_FIELDS = ["input", "output", "expected", "metadata", "context", "scores", "metrics"]
 from .xact_ids import prettify_xact
 
-Metadata = Dict[str, Any]
+Metadata = dict[str, Any]
 DATA_API_VERSION = 2
 
 T = TypeVar("T")
@@ -161,12 +153,12 @@ class Span(Exportable, contextlib.AbstractContextManager, ABC):
     @abstractmethod
     def start_span(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-        start_time: Optional[float] = None,
-        set_current: Optional[bool] = None,
-        parent: Optional[str] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+        start_time: float | None = None,
+        set_current: bool | None = None,
+        parent: str | None = None,
         **event: Any,
     ) -> "Span":
         """Create a new span. This is useful if you want to log more detailed trace information beyond the scope of a single log event. Data logged over several calls to `Span.log` will be merged into one logical row.
@@ -224,7 +216,7 @@ class Span(Exportable, contextlib.AbstractContextManager, ABC):
         """
 
     @abstractmethod
-    def end(self, end_time: Optional[float] = None) -> float:
+    def end(self, end_time: float | None = None) -> float:
         """Log an end time to the span (defaults to the current time). Returns the logged time.
 
         Will be invoked automatically if the span is bound to a context manager.
@@ -238,15 +230,15 @@ class Span(Exportable, contextlib.AbstractContextManager, ABC):
         """Flush any pending rows to the server."""
 
     @abstractmethod
-    def close(self, end_time: Optional[float] = None) -> float:
+    def close(self, end_time: float | None = None) -> float:
         """Alias for `end`."""
 
     @abstractmethod
     def set_attributes(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
     ) -> None:
         """Set the span's name, type, or other attributes. These attributes will be attached to all log events within the span.
         The attributes are equivalent to the arguments to start_span.
@@ -287,17 +279,17 @@ class _NoopSpan(Span):
 
     def start_span(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-        start_time: Optional[float] = None,
-        set_current: Optional[bool] = None,
-        parent: Optional[str] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+        start_time: float | None = None,
+        set_current: bool | None = None,
+        parent: str | None = None,
         **event: Any,
     ):
         return self
 
-    def end(self, end_time: Optional[float] = None) -> float:
+    def end(self, end_time: float | None = None) -> float:
         return end_time or time.time()
 
     def export(self):
@@ -312,14 +304,14 @@ class _NoopSpan(Span):
     def flush(self):
         pass
 
-    def close(self, end_time: Optional[float] = None) -> float:
+    def close(self, end_time: float | None = None) -> float:
         return self.end(end_time)
 
     def set_attributes(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
     ):
         pass
 
@@ -334,9 +326,9 @@ class _NoopSpan(Span):
 
     def __exit__(
         self,
-        exc_type: Optional[Type[BaseException]],
-        exc_value: Optional[BaseException],
-        traceback: Optional[TracebackType],
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
     ):
         pass
 
@@ -348,11 +340,11 @@ NOOP_SPAN_PERMALINK = "https://www.braintrust.dev/noop-span"
 class BraintrustState:
     def __init__(self):
         self.id = str(uuid.uuid4())
-        self.current_experiment: Optional[Experiment] = None
-        self.current_logger: contextvars.ContextVar[Optional[Logger]] = contextvars.ContextVar(
+        self.current_experiment: Experiment | None = None
+        self.current_logger: contextvars.ContextVar[Logger | None] = contextvars.ContextVar(
             "braintrust_current_logger", default=None
         )
-        self.current_parent: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+        self.current_parent: contextvars.ContextVar[str | None] = contextvars.ContextVar(
             "braintrust_current_parent", default=None
         )
         self.current_span: contextvars.ContextVar[Span] = contextvars.ContextVar(
@@ -402,20 +394,20 @@ class BraintrustState:
         )
 
     def reset_login_info(self):
-        self.app_url: Optional[str] = None
-        self.app_public_url: Optional[str] = None
-        self.login_token: Optional[str] = None
-        self.org_id: Optional[str] = None
-        self.org_name: Optional[str] = None
-        self.api_url: Optional[str] = None
-        self.proxy_url: Optional[str] = None
+        self.app_url: str | None = None
+        self.app_public_url: str | None = None
+        self.login_token: str | None = None
+        self.org_id: str | None = None
+        self.org_name: str | None = None
+        self.api_url: str | None = None
+        self.proxy_url: str | None = None
         self.logged_in: bool = False
-        self.git_metadata_settings: Optional[GitMetadataSettings] = None
+        self.git_metadata_settings: GitMetadataSettings | None = None
 
-        self._app_conn: Optional[HTTPConnection] = None
-        self._api_conn: Optional[HTTPConnection] = None
-        self._proxy_conn: Optional[HTTPConnection] = None
-        self._user_info: Optional[Mapping[str, Any]] = None
+        self._app_conn: HTTPConnection | None = None
+        self._api_conn: HTTPConnection | None = None
+        self._proxy_conn: HTTPConnection | None = None
+        self._user_info: Mapping[str, Any] | None = None
 
     def reset_parent_state(self):
         # reset possible parent state for tests
@@ -480,9 +472,9 @@ class BraintrustState:
 
     def login(
         self,
-        app_url: Optional[str] = None,
-        api_key: Optional[str] = None,
-        org_name: Optional[str] = None,
+        app_url: str | None = None,
+        api_key: str | None = None,
+        org_name: str | None = None,
         force_login: bool = False,
     ) -> None:
         if not force_login and self.logged_in:
@@ -558,7 +550,7 @@ class BraintrustState:
         bg_logger = self._global_bg_logger.get()
         bg_logger.enforce_queue_size_limit(enforce)
 
-    def set_masking_function(self, masking_function: Optional[Callable[[Any], Any]]) -> None:
+    def set_masking_function(self, masking_function: Callable[[Any], Any] | None) -> None:
         """Set the masking function on the background logger."""
         self.global_bg_logger().set_masking_function(masking_function)
 
@@ -566,7 +558,7 @@ class BraintrustState:
 _state: BraintrustState = None  # type: ignore
 
 
-_http_adapter: Optional[HTTPAdapter] = None
+_http_adapter: HTTPAdapter | None = None
 
 
 def set_http_adapter(adapter: HTTPAdapter) -> None:
@@ -632,7 +624,7 @@ class RetryRequestExceptionsAdapter(HTTPAdapter):
 
 
 class HTTPConnection:
-    def __init__(self, base_url: str, adapter: Optional[HTTPAdapter] = None):
+    def __init__(self, base_url: str, adapter: HTTPAdapter | None = None):
         self.base_url = base_url
         self.token = None
         self.adapter = adapter
@@ -661,7 +653,7 @@ class HTTPConnection:
         self.token = token
         self._set_session_token()
 
-    def _set_adapter(self, adapter: Optional[HTTPAdapter]) -> None:
+    def _set_adapter(self, adapter: HTTPAdapter | None) -> None:
         self.adapter = adapter
 
     def _reset(self, **retry_kwargs: Any) -> None:
@@ -693,9 +685,7 @@ class HTTPConnection:
     def delete(self, path: str, *args: Any, **kwargs: Any) -> requests.Response:
         return self.session.delete(_urljoin(self.base_url, path), *args, **kwargs)
 
-    def get_json(
-        self, object_type: str, args: Optional[Mapping[str, Any]] = None, retries: int = 0
-    ) -> Mapping[str, Any]:
+    def get_json(self, object_type: str, args: Mapping[str, Any] | None = None, retries: int = 0) -> Mapping[str, Any]:
         tries = retries + 1
         for i in range(tries):
             resp = self.get(f"/{object_type}", params=args)
@@ -708,7 +698,7 @@ class HTTPConnection:
         # Needed for type checking.
         raise Exception("unreachable")
 
-    def post_json(self, object_type: str, args: Optional[Mapping[str, Any]] = None) -> Any:
+    def post_json(self, object_type: str, args: Mapping[str, Any] | None = None) -> Any:
         resp = self.post(f"/{object_type.lstrip('/')}", json=args)
         response_raise_for_status(resp)
         return resp.json()
@@ -792,11 +782,11 @@ def _apply_masking_to_field(masking_function: Callable[[Any], Any], data: Any, f
 
 class _BackgroundLogger(ABC):
     @abstractmethod
-    def log(self, *args: LazyValue[Dict[str, Any]]) -> None:
+    def log(self, *args: LazyValue[dict[str, Any]]) -> None:
         pass
 
     @abstractmethod
-    def flush(self, batch_size: Optional[int] = None):
+    def flush(self, batch_size: int | None = None):
         pass
 
 
@@ -804,20 +794,20 @@ class _MemoryBackgroundLogger(_BackgroundLogger):
     def __init__(self):
         self.lock = threading.Lock()
         self.logs = []
-        self.masking_function: Optional[Callable[[Any], Any]] = None
+        self.masking_function: Callable[[Any], Any] | None = None
 
     def enforce_queue_size_limit(self, enforce: bool) -> None:
         pass
 
-    def log(self, *args: LazyValue[Dict[str, Any]]) -> None:
+    def log(self, *args: LazyValue[dict[str, Any]]) -> None:
         with self.lock:
             self.logs.extend(args)
 
-    def set_masking_function(self, masking_function: Optional[Callable[[Any], Any]]) -> None:
+    def set_masking_function(self, masking_function: Callable[[Any], Any] | None) -> None:
         """Set the masking function for the memory logger."""
         self.masking_function = masking_function
 
-    def flush(self, batch_size: Optional[int] = None):
+    def flush(self, batch_size: int | None = None):
         pass
 
     def pop(self):
@@ -871,7 +861,7 @@ BACKGROUND_LOGGER_BASE_SLEEP_TIME_S = 1.0
 class _HTTPBackgroundLogger:
     def __init__(self, api_conn: LazyValue[HTTPConnection]):
         self.api_conn = api_conn
-        self.masking_function: Optional[Callable[[Any], Any]] = None
+        self.masking_function: Callable[[Any], Any] | None = None
         self.outfile = sys.stderr
         self.flush_lock = threading.RLock()
 
@@ -934,7 +924,7 @@ class _HTTPBackgroundLogger:
         """
         self.queue.enforce_queue_size_limit(enforce)
 
-    def log(self, *args: LazyValue[Dict[str, Any]]) -> None:
+    def log(self, *args: LazyValue[dict[str, Any]]) -> None:
         self._start()
         dropped_items = []
         for event in args:
@@ -981,7 +971,7 @@ class _HTTPBackgroundLogger:
                     else:
                         raise
 
-    def flush(self, batch_size: Optional[int] = None):
+    def flush(self, batch_size: int | None = None):
         if batch_size is None:
             batch_size = self.default_batch_size
 
@@ -1020,7 +1010,7 @@ class _HTTPBackgroundLogger:
                         f"Encountered the following errors while logging:", post_promise_exceptions
                     )
 
-            attachment_errors: List[Exception] = []
+            attachment_errors: list[Exception] = []
             for attachment in attachments:
                 try:
                     result = attachment.upload()
@@ -1038,8 +1028,8 @@ class _HTTPBackgroundLogger:
                 )
 
     def _unwrap_lazy_values(
-        self, wrapped_items: Sequence[LazyValue[Dict[str, Any]]]
-    ) -> Tuple[List[List[Dict[str, Any]]], List["BaseAttachment"]]:
+        self, wrapped_items: Sequence[LazyValue[dict[str, Any]]]
+    ) -> tuple[list[list[dict[str, Any]]], list["BaseAttachment"]]:
         for i in range(self.num_tries):
             try:
                 unwrapped_items = [item.get() for item in wrapped_items]
@@ -1069,7 +1059,7 @@ class _HTTPBackgroundLogger:
 
                             batched_items[batch_idx][item_idx] = masked_item
 
-                attachments: List["BaseAttachment"] = []
+                attachments: list["BaseAttachment"] = []
                 for batch in batched_items:
                     for item in batch:
                         _extract_attachments(item, attachments)
@@ -1179,7 +1169,7 @@ class _HTTPBackgroundLogger:
     def internal_replace_api_conn(self, api_conn: HTTPConnection):
         self.api_conn = LazyValue(lambda: api_conn, use_mutex=False)
 
-    def set_masking_function(self, masking_function: Optional[Callable[[Any], Any]]):
+    def set_masking_function(self, masking_function: Callable[[Any], Any] | None):
         """Set or update the masking function."""
         self.masking_function = masking_function
 
@@ -1221,7 +1211,7 @@ def _internal_with_memory_background_logger():
 class ObjectMetadata:
     id: str
     name: str
-    full_info: Dict[str, Any]
+    full_info: dict[str, Any]
 
 
 @dataclasses.dataclass
@@ -1250,69 +1240,69 @@ class OrgProjectMetadata:
 # this.
 @overload
 def init(
-    project: Optional[str] = ...,
-    experiment: Optional[str] = ...,
-    description: Optional[str] = ...,
+    project: str | None = ...,
+    experiment: str | None = ...,
+    description: str | None = ...,
     dataset: Optional["Dataset"] = ...,
     open: Literal[False] = ...,
-    base_experiment: Optional[str] = ...,
+    base_experiment: str | None = ...,
     is_public: bool = ...,
-    app_url: Optional[str] = ...,
-    api_key: Optional[str] = ...,
-    org_name: Optional[str] = ...,
-    metadata: Optional[Metadata] = ...,
-    git_metadata_settings: Optional[GitMetadataSettings] = ...,
+    app_url: str | None = ...,
+    api_key: str | None = ...,
+    org_name: str | None = ...,
+    metadata: Metadata | None = ...,
+    git_metadata_settings: GitMetadataSettings | None = ...,
     set_current: bool = ...,
-    update: Optional[bool] = ...,
-    project_id: Optional[str] = ...,
-    base_experiment_id: Optional[str] = ...,
-    repo_info: Optional[RepoInfo] = ...,
-    state: Optional[BraintrustState] = ...,
+    update: bool | None = ...,
+    project_id: str | None = ...,
+    base_experiment_id: str | None = ...,
+    repo_info: RepoInfo | None = ...,
+    state: BraintrustState | None = ...,
 ) -> "Experiment": ...
 
 
 @overload
 def init(
-    project: Optional[str] = ...,
-    experiment: Optional[str] = ...,
-    description: Optional[str] = ...,
+    project: str | None = ...,
+    experiment: str | None = ...,
+    description: str | None = ...,
     dataset: Optional["Dataset"] = ...,
     open: Literal[True] = ...,
-    base_experiment: Optional[str] = ...,
+    base_experiment: str | None = ...,
     is_public: bool = ...,
-    app_url: Optional[str] = ...,
-    api_key: Optional[str] = ...,
-    org_name: Optional[str] = ...,
-    metadata: Optional[Metadata] = ...,
-    git_metadata_settings: Optional[GitMetadataSettings] = ...,
+    app_url: str | None = ...,
+    api_key: str | None = ...,
+    org_name: str | None = ...,
+    metadata: Metadata | None = ...,
+    git_metadata_settings: GitMetadataSettings | None = ...,
     set_current: bool = ...,
-    update: Optional[bool] = ...,
-    project_id: Optional[str] = ...,
-    base_experiment_id: Optional[str] = ...,
-    repo_info: Optional[RepoInfo] = ...,
-    state: Optional[BraintrustState] = ...,
+    update: bool | None = ...,
+    project_id: str | None = ...,
+    base_experiment_id: str | None = ...,
+    repo_info: RepoInfo | None = ...,
+    state: BraintrustState | None = ...,
 ) -> "ReadonlyExperiment": ...
 
 
 def init(
-    project: Optional[str] = None,
-    experiment: Optional[str] = None,
-    description: Optional[str] = None,
+    project: str | None = None,
+    experiment: str | None = None,
+    description: str | None = None,
     dataset: Optional["Dataset"] = None,
     open: bool = False,
-    base_experiment: Optional[str] = None,
+    base_experiment: str | None = None,
     is_public: bool = False,
-    app_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    org_name: Optional[str] = None,
-    metadata: Optional[Metadata] = None,
-    git_metadata_settings: Optional[GitMetadataSettings] = None,
+    app_url: str | None = None,
+    api_key: str | None = None,
+    org_name: str | None = None,
+    metadata: Metadata | None = None,
+    git_metadata_settings: GitMetadataSettings | None = None,
     set_current: bool = True,
-    update: Optional[bool] = None,
-    project_id: Optional[str] = None,
-    base_experiment_id: Optional[str] = None,
-    repo_info: Optional[RepoInfo] = None,
-    state: Optional[BraintrustState] = None,
+    update: bool | None = None,
+    project_id: str | None = None,
+    base_experiment_id: str | None = None,
+    repo_info: RepoInfo | None = None,
+    state: BraintrustState | None = None,
 ) -> Union["Experiment", "ReadonlyExperiment"]:
     """
     Log in, and then initialize a new experiment in a specified project. If the project does not exist, it will be created.
@@ -1460,18 +1450,18 @@ def init_experiment(*args, **kwargs) -> Union["Experiment", "ReadonlyExperiment"
 
 
 def init_dataset(
-    project: Optional[str] = None,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    version: Optional[Union[str, int]] = None,
-    app_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    org_name: Optional[str] = None,
-    project_id: Optional[str] = None,
-    metadata: Optional[Metadata] = None,
+    project: str | None = None,
+    name: str | None = None,
+    description: str | None = None,
+    version: str | int | None = None,
+    app_url: str | None = None,
+    api_key: str | None = None,
+    org_name: str | None = None,
+    project_id: str | None = None,
+    metadata: Metadata | None = None,
     use_output: bool = DEFAULT_IS_LEGACY_DATASET,
-    _internal_btql: Optional[Dict[str, Any]] = None,
-    state: Optional[BraintrustState] = None,
+    _internal_btql: dict[str, Any] | None = None,
+    state: BraintrustState | None = None,
 ) -> "Dataset":
     """
     Create a new dataset in a specified project. If the project does not exist, it will be created.
@@ -1519,7 +1509,7 @@ def init_dataset(
     )
 
 
-def _compute_logger_metadata(project_name: Optional[str] = None, project_id: Optional[str] = None):
+def _compute_logger_metadata(project_name: str | None = None, project_id: str | None = None):
     login()
     org_id = _state.org_id
     if project_id is None:
@@ -1547,15 +1537,15 @@ def _compute_logger_metadata(project_name: Optional[str] = None, project_id: Opt
 
 
 def init_logger(
-    project: Optional[str] = None,
-    project_id: Optional[str] = None,
+    project: str | None = None,
+    project_id: str | None = None,
     async_flush: bool = True,
-    app_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    org_name: Optional[str] = None,
+    app_url: str | None = None,
+    api_key: str | None = None,
+    org_name: str | None = None,
     force_login: bool = False,
     set_current: bool = True,
-    state: Optional[BraintrustState] = None,
+    state: BraintrustState | None = None,
 ) -> "Logger":
     """
     Create a new logger in a specified project. If the project does not exist, it will be created.
@@ -1604,17 +1594,17 @@ def init_logger(
 
 
 def load_prompt(
-    project: Optional[str] = None,
-    slug: Optional[str] = None,
-    version: Optional[Union[str, int]] = None,
-    project_id: Optional[str] = None,
-    id: Optional[str] = None,
-    defaults: Optional[Mapping[str, Any]] = None,
+    project: str | None = None,
+    slug: str | None = None,
+    version: str | int | None = None,
+    project_id: str | None = None,
+    id: str | None = None,
+    defaults: Mapping[str, Any] | None = None,
     no_trace: bool = False,
-    environment: Optional[str] = None,
-    app_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    org_name: Optional[str] = None,
+    environment: str | None = None,
+    app_url: str | None = None,
+    api_key: str | None = None,
+    org_name: str | None = None,
 ) -> "Prompt":
     """
     Loads a prompt from the specified project.
@@ -1737,9 +1727,9 @@ login_lock = threading.RLock()
 
 
 def login(
-    app_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    org_name: Optional[str] = None,
+    app_url: str | None = None,
+    api_key: str | None = None,
+    org_name: str | None = None,
     force_login: bool = False,
 ) -> None:
     """
@@ -1763,9 +1753,9 @@ def login(
 
 
 def login_to_state(
-    app_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    org_name: Optional[str] = None,
+    app_url: str | None = None,
+    api_key: str | None = None,
+    org_name: str | None = None,
 ) -> BraintrustState:
     app_url = _get_app_url(app_url)
 
@@ -1845,7 +1835,7 @@ def login_to_state(
     return state
 
 
-def set_masking_function(masking_function: Optional[Callable[[Any], Any]]) -> None:
+def set_masking_function(masking_function: Callable[[Any], Any] | None) -> None:
     """
     Set a global masking function that will be applied to all logged data before sending to Braintrust.
     The masking function will be applied after records are merged but before they are sent to the backend.
@@ -1872,7 +1862,7 @@ def log(**event: Any) -> str:
     return e.log(**event)
 
 
-def summarize(summarize_scores: bool = True, comparison_experiment_id: Optional[str] = None) -> "ExperimentSummary":
+def summarize(summarize_scores: bool = True, comparison_experiment_id: str | None = None) -> "ExperimentSummary":
     """
     Summarize the current experiment, including the scores (compared to the closest reference experiment) and metadata.
 
@@ -1918,7 +1908,7 @@ def current_span() -> Span:
 
 
 @contextlib.contextmanager
-def parent_context(parent: Optional[str], state: Optional[BraintrustState] = None):
+def parent_context(parent: str | None, state: BraintrustState | None = None):
     """
     Context manager to temporarily set the parent context for spans.
 
@@ -1940,7 +1930,7 @@ def parent_context(parent: Optional[str], state: Optional[BraintrustState] = Non
 
 
 def get_span_parent_object(
-    parent: Optional[str] = None, state: Optional[BraintrustState] = None
+    parent: str | None = None, state: BraintrustState | None = None
 ) -> Union[SpanComponentsV4, "Logger", "Experiment", Span]:
     """Mainly for internal use. Return the parent object for starting a span in a global context.
     Applies precedence: current span > propagated parent string > experiment > logger."""
@@ -2155,14 +2145,14 @@ def traced(*span_args: Any, **span_kwargs: Any) -> Callable[[F], F]:
 
 
 def start_span(
-    name: Optional[str] = None,
-    type: Optional[SpanTypeAttribute] = None,
-    span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-    start_time: Optional[float] = None,
-    set_current: Optional[bool] = None,
-    parent: Optional[str] = None,
-    propagated_event: Optional[Dict[str, Any]] = None,
-    state: Optional[BraintrustState] = None,
+    name: str | None = None,
+    type: SpanTypeAttribute | None = None,
+    span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+    start_time: float | None = None,
+    set_current: bool | None = None,
+    parent: str | None = None,
+    propagated_event: dict[str, Any] | None = None,
+    state: BraintrustState | None = None,
     **event: Any,
 ) -> Span:
     """Lower-level alternative to `@traced` for starting a span at the toplevel. It creates a span under the first active object (using the same precedence order as `@traced`), or if `parent` is specified, under the specified parent row, or returns a no-op span object.
@@ -2265,7 +2255,7 @@ def validate_tags(tags: Sequence[str]) -> None:
         seen.add(tag)
 
 
-def _extract_attachments(event: Dict[str, Any], attachments: List["BaseAttachment"]) -> None:
+def _extract_attachments(event: dict[str, Any], attachments: list["BaseAttachment"]) -> None:
     """
     Helper function for uploading attachments. Recursively extracts `Attachment`
     and `ExternalAttachment` values and replaces them with their associated
@@ -2282,13 +2272,13 @@ def _extract_attachments(event: Dict[str, Any], attachments: List["BaseAttachmen
             return v.reference  # Attachment cannot be nested.
 
         # Recursive case: object.
-        if isinstance(v, Dict):
+        if isinstance(v, dict):
             for k, v2 in v.items():
                 v[k] = _helper(v2)
             return v
 
         # Recursive case: array.
-        if isinstance(v, List):
+        if isinstance(v, list):
             for i in range(len(v)):
                 v[i] = _helper(v[i])
             return v
@@ -2308,7 +2298,7 @@ def _enrich_attachments(event: TMutableMapping) -> TMutableMapping:
     """
 
     def _helper(v: Any) -> Any:
-        if isinstance(v, Dict):
+        if isinstance(v, dict):
             # Base case: AttachmentReference.
             if v.get("type") == "braintrust_attachment" or v.get("type") == "external_attachment":
                 return ReadonlyAttachment(cast(AttachmentReference, v))
@@ -2319,7 +2309,7 @@ def _enrich_attachments(event: TMutableMapping) -> TMutableMapping:
                 return v
 
         # Recursive case: array.
-        if isinstance(v, List):
+        if isinstance(v, list):
             for i in range(len(v)):
                 v[i] = _helper(v[i])
             return v
@@ -2333,7 +2323,7 @@ def _enrich_attachments(event: TMutableMapping) -> TMutableMapping:
     return event
 
 
-def _validate_and_sanitize_experiment_log_partial_args(event: Mapping[str, Any]) -> Dict[str, Any]:
+def _validate_and_sanitize_experiment_log_partial_args(event: Mapping[str, Any]) -> dict[str, Any]:
     # Make sure only certain keys are specified.
     forbidden_keys = set(event.keys()) - {
         "input",
@@ -2436,7 +2426,7 @@ def _validate_and_sanitize_experiment_log_full_args(event: Mapping[str, Any], ha
     return event
 
 
-def _deep_copy_event(event: Mapping[str, Any]) -> Dict[str, Any]:
+def _deep_copy_event(event: Mapping[str, Any]) -> dict[str, Any]:
     """
     Creates a deep copy of the given event. Replaces references to user objects
     with placeholder strings to ensure serializability, except for `Attachment`
@@ -2460,7 +2450,7 @@ def _deep_copy_event(event: Mapping[str, Any]) -> Dict[str, Any]:
 
         # Check for circular references in mutable containers
         # Use id() to track object identity
-        if isinstance(v, (Mapping, List, Tuple, Set)):
+        if isinstance(v, (Mapping, list, tuple, set)):
             obj_id = id(v)
             if obj_id in visited:
                 return "<circular reference>"
@@ -2481,7 +2471,7 @@ def _deep_copy_event(event: Mapping[str, Any]) -> Dict[str, Any]:
                             key_str = f"<non-stringifiable-key: {type(k).__name__}>"
                         result[key_str] = _deep_copy_object(v[k], depth + 1)
                     return result
-                elif isinstance(v, (List, Tuple, Set)):
+                elif isinstance(v, (list, tuple, set)):
                     return [_deep_copy_object(x, depth + 1) for x in v]
             finally:
                 # Remove from visited set after processing to allow the same object
@@ -2547,9 +2537,9 @@ class ObjectFetcher(ABC, Generic[TMapping]):
     def __init__(
         self,
         object_type: str,
-        pinned_version: Union[None, int, str] = None,
-        mutate_record: Optional[Callable[[TMapping], TMapping]] = None,
-        _internal_btql: Optional[Dict[str, Any]] = None,
+        pinned_version: None | int | str = None,
+        mutate_record: Callable[[TMapping], TMapping] | None = None,
+        _internal_btql: dict[str, Any] | None = None,
     ):
         self.object_type = object_type
 
@@ -2563,10 +2553,10 @@ class ObjectFetcher(ABC, Generic[TMapping]):
         self._pinned_version = str(pinned_version) if pinned_version is not None else None
         self._mutate_record = mutate_record
 
-        self._fetched_data: Optional[List[TMapping]] = None
+        self._fetched_data: list[TMapping] | None = None
         self._internal_btql = _internal_btql
 
-    def fetch(self, batch_size: Optional[int] = None) -> Iterator[TMapping]:
+    def fetch(self, batch_size: int | None = None) -> Iterator[TMapping]:
         """
         Fetch all records.
 
@@ -2601,7 +2591,7 @@ class ObjectFetcher(ABC, Generic[TMapping]):
     @abstractmethod
     def id(self) -> str: ...
 
-    def _refetch(self, batch_size: Optional[int] = None) -> List[TMapping]:
+    def _refetch(self, batch_size: int | None = None) -> list[TMapping]:
         state = self._get_state()
         limit = batch_size if batch_size is not None else DEFAULT_FETCH_BATCH_SIZE
         if self._fetched_data is None:
@@ -2642,7 +2632,7 @@ class ObjectFetcher(ABC, Generic[TMapping]):
                 )
                 response_raise_for_status(resp)
                 resp_json = resp.json()
-                data = (data or []) + cast(List[TMapping], resp_json["data"])
+                data = (data or []) + cast(list[TMapping], resp_json["data"])
                 if not resp_json.get("cursor", None):
                     break
                 cursor = resp_json.get("cursor", None)
@@ -2699,7 +2689,7 @@ class Attachment(BaseAttachment):
     def __init__(
         self,
         *,
-        data: Union[str, bytes, bytearray],
+        data: str | bytes | bytearray,
         filename: str,
         content_type: str,
     ):
@@ -2770,7 +2760,7 @@ class Attachment(BaseAttachment):
             try:
                 data = self._data.get()
             except Exception as e:
-                raise IOError(f"Failed to read file: {e}") from e
+                raise OSError(f"Failed to read file: {e}") from e
 
             signed_url = metadata.get("signedUrl")
             headers = metadata.get("headers")
@@ -2823,7 +2813,7 @@ class Attachment(BaseAttachment):
 
         return LazyValue(error_wrapper, use_mutex=True)
 
-    def _init_data(self, data: Union[str, bytes, bytearray]) -> LazyValue[bytes]:
+    def _init_data(self, data: str | bytes | bytearray) -> LazyValue[bytes]:
         if isinstance(data, str):
             self._ensure_file_readable(data)
 
@@ -3041,11 +3031,11 @@ def _log_feedback_impl(
     parent_object_type: SpanObjectTypeV3,
     parent_object_id: LazyValue[str],
     id: str,
-    scores: Optional[Mapping[str, Union[int, float]]] = None,
-    expected: Optional[Any] = None,
-    tags: Optional[Sequence[str]] = None,
-    comment: Optional[str] = None,
-    metadata: Optional[Mapping[str, Any]] = None,
+    scores: Mapping[str, int | float] | None = None,
+    expected: Any | None = None,
+    tags: Sequence[str] | None = None,
+    comment: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
     source: Literal["external", "app", "api", None] = None,
 ):
     if source is None:
@@ -3185,13 +3175,13 @@ class SpanIds:
 
     span_id: str
     root_span_id: str
-    span_parents: Optional[List[str]]
+    span_parents: list[str] | None
 
 
 def _resolve_span_ids(
-    span_id: Optional[str],
-    root_span_id: Optional[str],
-    parent_span_ids: Optional[ParentSpanIds],
+    span_id: str | None,
+    root_span_id: str | None,
+    parent_span_ids: ParentSpanIds | None,
     lookup_span_parent: bool,
     id_generator: "id_gen.IDGenerator",
     context_manager: "context.ContextManager",
@@ -3265,7 +3255,7 @@ def span_components_to_object_id(components: SpanComponentsV4) -> str:
     return _span_components_to_object_id_lambda(components)()
 
 
-def permalink(slug: str, org_name: Optional[str] = None, app_url: Optional[str] = None) -> str:
+def permalink(slug: str, org_name: str | None = None, app_url: str | None = None) -> str:
     """
     Format a permalink to the Braintrust application for viewing the span represented by the provided `slug`.
 
@@ -3314,13 +3304,13 @@ def permalink(slug: str, org_name: Optional[str] = None, app_url: Optional[str]
 
 
 def _start_span_parent_args(
-    parent: Optional[str],
+    parent: str | None,
     parent_object_type: SpanObjectTypeV3,
     parent_object_id: LazyValue[str],
-    parent_compute_object_metadata_args: Optional[Dict[str, Any]],
-    parent_span_ids: Optional[ParentSpanIds],
-    propagated_event: Optional[Dict[str, Any]],
-) -> Dict[str, Any]:
+    parent_compute_object_metadata_args: dict[str, Any] | None,
+    parent_span_ids: ParentSpanIds | None,
+    propagated_event: dict[str, Any] | None,
+) -> dict[str, Any]:
     if parent:
         assert parent_span_ids is None, "Cannot specify both parent and parent_span_ids"
         parent_components = SpanComponentsV4.from_str(parent)
@@ -3374,9 +3364,9 @@ class _ExperimentDatasetEvent(TypedDict):
 
     id: str
     _xact_id: str
-    input: Optional[Any]
-    expected: Optional[Any]
-    tags: Optional[Sequence[str]]
+    input: Any | None
+    expected: Any | None
+    tags: Sequence[str] | None
 
 
 class ExperimentDatasetIterator:
@@ -3422,7 +3412,7 @@ class Experiment(ObjectFetcher[ExperimentEvent], Exportable):
         self,
         lazy_metadata: LazyValue[ProjectExperimentMetadata],
         dataset: Optional["Dataset"] = None,
-        state: Optional[BraintrustState] = None,
+        state: BraintrustState | None = None,
     ):
         self._lazy_metadata = lazy_metadata
         self.dataset = dataset
@@ -3473,16 +3463,16 @@ class Experiment(ObjectFetcher[ExperimentEvent], Exportable):
 
     def log(
         self,
-        input: Optional[Any] = None,
-        output: Optional[Any] = None,
-        expected: Optional[Any] = None,
-        error: Optional[str] = None,
-        tags: Optional[Sequence[str]] = None,
-        scores: Optional[Mapping[str, Union[int, float]]] = None,
-        metadata: Optional[Mapping[str, Any]] = None,
-        metrics: Optional[Mapping[str, Union[int, float]]] = None,
-        id: Optional[str] = None,
-        dataset_record_id: Optional[str] = None,
+        input: Any | None = None,
+        output: Any | None = None,
+        expected: Any | None = None,
+        error: str | None = None,
+        tags: Sequence[str] | None = None,
+        scores: Mapping[str, int | float] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        metrics: Mapping[str, int | float] | None = None,
+        id: str | None = None,
+        dataset_record_id: str | None = None,
         allow_concurrent_with_spans: bool = False,
     ) -> str:
         """
@@ -3527,11 +3517,11 @@ class Experiment(ObjectFetcher[ExperimentEvent], Exportable):
     def log_feedback(
         self,
         id: str,
-        scores: Optional[Mapping[str, Union[int, float]]] = None,
-        expected: Optional[Any] = None,
-        tags: Optional[Sequence[str]] = None,
-        comment: Optional[str] = None,
-        metadata: Optional[Mapping[str, Any]] = None,
+        scores: Mapping[str, int | float] | None = None,
+        expected: Any | None = None,
+        tags: Sequence[str] | None = None,
+        comment: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
         source: Literal["external", "app", "api", None] = None,
     ) -> None:
         """
@@ -3559,13 +3549,13 @@ class Experiment(ObjectFetcher[ExperimentEvent], Exportable):
 
     def start_span(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-        start_time: Optional[float] = None,
-        set_current: Optional[bool] = None,
-        parent: Optional[str] = None,
-        propagated_event: Optional[Dict[str, Any]] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+        start_time: float | None = None,
+        set_current: bool | None = None,
+        parent: str | None = None,
+        propagated_event: dict[str, Any] | None = None,
         **event: Any,
     ) -> Span:
         """Create a new toplevel span underneath the experiment. The name defaults to "root" and the span type to "eval".
@@ -3599,7 +3589,7 @@ class Experiment(ObjectFetcher[ExperimentEvent], Exportable):
             **event,
         )
 
-    def fetch_base_experiment(self) -> Optional[ExperimentIdentifier]:
+    def fetch_base_experiment(self) -> ExperimentIdentifier | None:
         state = self._get_state()
         conn = state.app_conn()
 
@@ -3616,7 +3606,7 @@ class Experiment(ObjectFetcher[ExperimentEvent], Exportable):
             return None
 
     def summarize(
-        self, summarize_scores: bool = True, comparison_experiment_id: Optional[str] = None
+        self, summarize_scores: bool = True, comparison_experiment_id: str | None = None
     ) -> "ExperimentSummary":
         """
         Summarize the experiment, including the scores (compared to the closest reference experiment) and metadata.
@@ -3703,13 +3693,13 @@ class Experiment(ObjectFetcher[ExperimentEvent], Exportable):
 
     def _start_span_impl(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-        start_time: Optional[float] = None,
-        set_current: Optional[bool] = None,
-        parent: Optional[str] = None,
-        propagated_event: Optional[Dict[str, Any]] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+        start_time: float | None = None,
+        set_current: bool | None = None,
+        parent: str | None = None,
+        propagated_event: dict[str, Any] | None = None,
         lookup_span_parent: bool = True,
         **event: Any,
     ) -> Span:
@@ -3739,9 +3729,9 @@ class Experiment(ObjectFetcher[ExperimentEvent], Exportable):
 
     def __exit__(
         self,
-        exc_type: Optional[Type[BaseException]],
-        exc_value: Optional[BaseException],
-        traceback: Optional[TracebackType],
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
     ) -> None:
         del exc_type, exc_value, traceback
 
@@ -3754,7 +3744,7 @@ class ReadonlyExperiment(ObjectFetcher[ExperimentEvent]):
     def __init__(
         self,
         lazy_metadata: LazyValue[ProjectExperimentMetadata],
-        state: Optional[BraintrustState] = None,
+        state: BraintrustState | None = None,
     ):
         self._lazy_metadata = lazy_metadata
         self.state = state or _state
@@ -3779,7 +3769,7 @@ class ReadonlyExperiment(ObjectFetcher[ExperimentEvent]):
         self._lazy_metadata.get()
         return self.state
 
-    def as_dataset(self, batch_size: Optional[int] = None) -> Iterator[_ExperimentDatasetEvent]:
+    def as_dataset(self, batch_size: int | None = None) -> Iterator[_ExperimentDatasetEvent]:
         """
         Return the experiment's data as a dataset iterator.
 
@@ -3805,19 +3795,19 @@ class SpanImpl(Span):
         self,
         parent_object_type: SpanObjectTypeV3,
         parent_object_id: LazyValue[str],
-        parent_compute_object_metadata_args: Optional[Dict[str, Any]],
-        parent_span_ids: Optional[ParentSpanIds],
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        default_root_type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-        start_time: Optional[float] = None,
-        set_current: Optional[bool] = None,
-        event: Optional[Dict[str, Any]] = None,
-        propagated_event: Optional[Dict[str, Any]] = None,
-        span_id: Optional[str] = None,
-        root_span_id: Optional[str] = None,
-        state: Optional[BraintrustState] = None,
+        parent_compute_object_metadata_args: dict[str, Any] | None,
+        parent_span_ids: ParentSpanIds | None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        default_root_type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+        start_time: float | None = None,
+        set_current: bool | None = None,
+        event: dict[str, Any] | None = None,
+        propagated_event: dict[str, Any] | None = None,
+        span_id: str | None = None,
+        root_span_id: str | None = None,
+        state: BraintrustState | None = None,
         lookup_span_parent: bool = True,
     ):
         if span_attributes is None:
@@ -3830,11 +3820,11 @@ class SpanImpl(Span):
         self.state = state or _state
 
         self.can_set_current = cast(bool, coalesce(set_current, True))
-        self._logged_end_time: Optional[float] = None
+        self._logged_end_time: float | None = None
 
         # Context token for proper cleanup - used by both OTEL and Braintrust context managers
         # This is set by the context manager when the span becomes active
-        self._context_token: Optional[Any] = None
+        self._context_token: Any | None = None
 
         self.parent_object_type = parent_object_type
         self.parent_object_id = parent_object_id
@@ -3867,7 +3857,7 @@ class SpanImpl(Span):
             _EXEC_COUNTER += 1
             exec_counter = _EXEC_COUNTER
 
-        internal_data: Dict[str, Any] = dict(
+        internal_data: dict[str, Any] = dict(
             metrics=dict(
                 start=start_time or time.time(),
             ),
@@ -3909,9 +3899,9 @@ class SpanImpl(Span):
 
     def set_attributes(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Mapping[str, Any]] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: Mapping[str, Any] | None = None,
     ) -> None:
         self.log_internal(
             internal_data={
@@ -3929,9 +3919,7 @@ class SpanImpl(Span):
     def log(self, **event: Any) -> None:
         return self.log_internal(event=event, internal_data=None)
 
-    def log_internal(
-        self, event: Optional[Dict[str, Any]] = None, internal_data: Optional[Dict[str, Any]] = None
-    ) -> None:
+    def log_internal(self, event: dict[str, Any] | None = None, internal_data: dict[str, Any] | None = None) -> None:
         serializable_partial_record, lazy_partial_record = split_logging_data(event, internal_data)
 
         # We both check for serializability and round-trip `partial_record`
@@ -3939,7 +3927,7 @@ class SpanImpl(Span):
         # cutting out any reference to user objects when the object is logged
         # asynchronously, so that in case the objects are modified, the logging
         # is unaffected.
-        partial_record: Dict[str, Any] = dict(
+        partial_record: dict[str, Any] = dict(
             id=self.id,
             span_id=self.span_id,
             root_span_id=self.root_span_id,
@@ -3956,7 +3944,7 @@ class SpanImpl(Span):
         if len(serializable_partial_record.get("tags", [])) > 0 and self.span_parents:
             raise Exception("Tags can only be logged to the root span")
 
-        def compute_record() -> Dict[str, Any]:
+        def compute_record() -> dict[str, Any]:
             exporter = _get_exporter()
             return dict(
                 **serializable_partial_record,
@@ -3979,13 +3967,13 @@ class SpanImpl(Span):
 
     def start_span(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-        start_time: Optional[float] = None,
-        set_current: Optional[bool] = None,
-        parent: Optional[str] = None,
-        propagated_event: Optional[Dict[str, Any]] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+        start_time: float | None = None,
+        set_current: bool | None = None,
+        parent: str | None = None,
+        propagated_event: dict[str, Any] | None = None,
         **event: Any,
     ) -> Span:
         if parent:
@@ -4017,7 +4005,7 @@ class SpanImpl(Span):
             state=self.state,
         )
 
-    def end(self, end_time: Optional[float] = None) -> float:
+    def end(self, end_time: float | None = None) -> float:
         internal_data = {}
         if not self._logged_end_time:
             end_time = end_time or time.time()
@@ -4162,13 +4150,13 @@ class SpanImpl(Span):
 
 
 def log_exc_info_to_span(
-    span: Span, exc_type: Type[BaseException], exc_value: BaseException, tb: Optional[TracebackType]
+    span: Span, exc_type: type[BaseException], exc_value: BaseException, tb: TracebackType | None
 ) -> None:
     error = stringify_exception(exc_type, exc_value, tb)
     span.log(error=error)
 
 
-def stringify_exception(exc_type: Type[BaseException], exc_value: BaseException, tb: Optional[TracebackType]) -> str:
+def stringify_exception(exc_type: type[BaseException], exc_value: BaseException, tb: TracebackType | None) -> str:
     return "".join(
         traceback.format_exception_only(exc_type, exc_value)
         + ["\nTraceback (most recent call last):\n"]
@@ -4183,8 +4171,8 @@ def _strip_nones(d: T, deep: bool) -> T:
 
 
 def split_logging_data(
-    event: Optional[Dict[str, Any]], internal_data: Optional[Dict[str, Any]]
-) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    event: dict[str, Any] | None, internal_data: dict[str, Any] | None
+) -> tuple[dict[str, Any], dict[str, Any]]:
     # There should be no overlap between the dictionaries being merged,
     # except for `sanitized` and `internal_data`, where the former overrides
     # the latter.
@@ -4192,8 +4180,8 @@ def split_logging_data(
     sanitized_and_internal_data = _strip_nones(internal_data or {}, deep=True)
     merge_dicts(sanitized_and_internal_data, _strip_nones(sanitized, deep=False))
 
-    serializable_partial_record: Dict[str, Any] = {}
-    lazy_partial_record: Dict[str, Any] = {}
+    serializable_partial_record: dict[str, Any] = {}
+    lazy_partial_record: dict[str, Any] = {}
     for k, v in sanitized_and_internal_data.items():
         if isinstance(v, BraintrustStream):
             # Python has weird semantics with loop variables and lambda functions, so we
@@ -4220,10 +4208,10 @@ class Dataset(ObjectFetcher[DatasetEvent]):
     def __init__(
         self,
         lazy_metadata: LazyValue[ProjectDatasetMetadata],
-        version: Union[None, int, str] = None,
+        version: None | int | str = None,
         legacy: bool = DEFAULT_IS_LEGACY_DATASET,
-        _internal_btql: Optional[Dict[str, Any]] = None,
-        state: Optional[BraintrustState] = None,
+        _internal_btql: dict[str, Any] | None = None,
+        state: BraintrustState | None = None,
     ):
         if legacy:
             eprint(
@@ -4231,7 +4219,7 @@ class Dataset(ObjectFetcher[DatasetEvent]):
             )
 
         def mutate_record(r: DatasetEvent) -> DatasetEvent:
-            _enrich_attachments(cast(Dict[str, Any], r))
+            _enrich_attachments(cast(dict[str, Any], r))
             return ensure_dataset_record(r, legacy)
 
         self._lazy_metadata = lazy_metadata
@@ -4278,10 +4266,10 @@ class Dataset(ObjectFetcher[DatasetEvent]):
 
     def _validate_event(
         self,
-        metadata: Optional[Dict[str, Any]] = None,
-        expected: Optional[Any] = None,
-        output: Optional[Any] = None,
-        tags: Optional[Sequence[str]] = None,
+        metadata: dict[str, Any] | None = None,
+        expected: Any | None = None,
+        output: Any | None = None,
+        tags: Sequence[str] | None = None,
     ):
         if metadata is not None:
             if not isinstance(metadata, dict):
@@ -4298,7 +4286,7 @@ class Dataset(ObjectFetcher[DatasetEvent]):
 
     def _create_args(
         self, id, input=None, expected=None, metadata=None, tags=None, output=None, is_merge=False
-    ) -> LazyValue[Dict[str, Any]]:
+    ) -> LazyValue[dict[str, Any]]:
         expected_value = expected if expected is not None else output
 
         args = _populate_args(
@@ -4319,7 +4307,7 @@ class Dataset(ObjectFetcher[DatasetEvent]):
         _check_json_serializable(args)
         args = _deep_copy_event(args)
 
-        def compute_args() -> Dict[str, Any]:
+        def compute_args() -> dict[str, Any]:
             return dict(
                 **args,
                 dataset_id=self.id,
@@ -4329,12 +4317,12 @@ class Dataset(ObjectFetcher[DatasetEvent]):
 
     def insert(
         self,
-        input: Optional[Any] = None,
-        expected: Optional[Any] = None,
-        tags: Optional[Sequence[str]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-        id: Optional[str] = None,
-        output: Optional[Any] = None,
+        input: Any | None = None,
+        expected: Any | None = None,
+        tags: Sequence[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        id: str | None = None,
+        output: Any | None = None,
     ) -> str:
         """
         Insert a single record to the dataset. The record will be batched and uploaded behind the scenes. If you pass in an `id`,
@@ -4373,10 +4361,10 @@ class Dataset(ObjectFetcher[DatasetEvent]):
     def update(
         self,
         id: str,
-        input: Optional[Any] = None,
-        expected: Optional[Any] = None,
-        tags: Optional[Sequence[str]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
+        input: Any | None = None,
+        expected: Any | None = None,
+        tags: Sequence[str] | None = None,
+        metadata: dict[str, Any] | None = None,
     ) -> str:
         """
         Update fields of a single record in the dataset. The updated fields will be batched and uploaded behind the scenes.
@@ -4488,7 +4476,7 @@ class Dataset(ObjectFetcher[DatasetEvent]):
 def render_message(render: Callable[[str], str], message: PromptMessage):
     base = {k: v for (k, v) in message.as_dict().items() if v is not None}
     # TODO: shouldn't load_prompt guarantee content is a PromptMessage?
-    content = cast(Union[str, List[Union[TextPart, ImagePart]], Dict[str, Any]], message.content)
+    content = cast(Union[str, list[Union[TextPart, ImagePart]], dict[str, Any]], message.content)
     if content is not None:
         if isinstance(content, str):
             base["content"] = render(content)
@@ -4552,7 +4540,7 @@ def render_message(render: Callable[[str], str], message: PromptMessage):
 
 
 def _create_custom_render():
-    def _get_key(key: str, scopes: List[Dict[str, Any]], warn: bool) -> Any:
+    def _get_key(key: str, scopes: list[dict[str, Any]], warn: bool) -> Any:
         thing = chevron.renderer._get_key(key, scopes, warn)  # type: ignore
         if isinstance(thing, str):
             return thing
@@ -4592,7 +4580,7 @@ def render_templated_object(obj: Any, args: Any) -> Any:
     return obj
 
 
-def render_prompt_params(params: Dict[str, Any], args: Any) -> Dict[str, Any]:
+def render_prompt_params(params: dict[str, Any], args: Any) -> dict[str, Any]:
     if not params:
         return params
 
@@ -4617,7 +4605,7 @@ def render_prompt_params(params: Dict[str, Any], args: Any) -> Dict[str, Any]:
     return {**params, "response_format": {**response_format, "json_schema": {**json_schema, "schema": parsed_schema}}}
 
 
-def render_mustache(template: str, data: Any, *, strict: bool = False, renderer: Optional[Callable[..., Any]] = None):
+def render_mustache(template: str, data: Any, *, strict: bool = False, renderer: Callable[..., Any] | None = None):
     if renderer is None:
         renderer = chevron.render
 
@@ -4694,7 +4682,7 @@ class Prompt:
         return self._lazy_metadata.get().slug
 
     @property
-    def prompt(self) -> Optional[PromptBlockData]:
+    def prompt(self) -> PromptBlockData | None:
         return self._lazy_metadata.get().prompt_data.prompt
 
     @property
@@ -4791,7 +4779,7 @@ class Prompt:
 
 
 class Project:
-    def __init__(self, name: Optional[str] = None, id: Optional[str] = None):
+    def __init__(self, name: str | None = None, id: str | None = None):
         self._name = name
         self._id = id
         self.init_lock = threading.RLock()
@@ -4831,9 +4819,9 @@ class Logger(Exportable):
         self,
         lazy_metadata: LazyValue[OrgProjectMetadata],
         async_flush: bool = True,
-        compute_metadata_args: Optional[Dict] = None,
-        link_args: Optional[Dict] = None,
-        state: Optional[BraintrustState] = None,
+        compute_metadata_args: dict | None = None,
+        link_args: dict | None = None,
+        state: BraintrustState | None = None,
     ):
         self._lazy_metadata = lazy_metadata
         self.async_flush = async_flush
@@ -4873,15 +4861,15 @@ class Logger(Exportable):
 
     def log(
         self,
-        input: Optional[Any] = None,
-        output: Optional[Any] = None,
-        expected: Optional[Any] = None,
-        error: Optional[str] = None,
-        tags: Optional[Sequence[str]] = None,
-        scores: Optional[Mapping[str, Union[int, float]]] = None,
-        metadata: Optional[Mapping[str, Any]] = None,
-        metrics: Optional[Mapping[str, Union[int, float]]] = None,
-        id: Optional[str] = None,
+        input: Any | None = None,
+        output: Any | None = None,
+        expected: Any | None = None,
+        error: str | None = None,
+        tags: Sequence[str] | None = None,
+        scores: Mapping[str, int | float] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        metrics: Mapping[str, int | float] | None = None,
+        id: str | None = None,
         allow_concurrent_with_spans: bool = False,
     ) -> str:
         """
@@ -4926,11 +4914,11 @@ class Logger(Exportable):
     def log_feedback(
         self,
         id: str,
-        scores: Optional[Mapping[str, Union[int, float]]] = None,
-        expected: Optional[Any] = None,
-        tags: Optional[Sequence[str]] = None,
-        comment: Optional[str] = None,
-        metadata: Optional[Mapping[str, Any]] = None,
+        scores: Mapping[str, int | float] | None = None,
+        expected: Any | None = None,
+        tags: Sequence[str] | None = None,
+        comment: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
         source: Literal["external", "app", "api", None] = None,
     ) -> None:
         """
@@ -4958,15 +4946,15 @@ class Logger(Exportable):
 
     def start_span(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-        start_time: Optional[float] = None,
-        set_current: Optional[bool] = None,
-        parent: Optional[str] = None,
-        propagated_event: Optional[Dict[str, Any]] = None,
-        span_id: Optional[str] = None,
-        root_span_id: Optional[str] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+        start_time: float | None = None,
+        set_current: bool | None = None,
+        parent: str | None = None,
+        propagated_event: dict[str, Any] | None = None,
+        span_id: str | None = None,
+        root_span_id: str | None = None,
         **event: Any,
     ) -> Span:
         """Create a new toplevel span underneath the logger. The name defaults to "root" and the span type to "task".
@@ -5004,15 +4992,15 @@ class Logger(Exportable):
 
     def _start_span_impl(
         self,
-        name: Optional[str] = None,
-        type: Optional[SpanTypeAttribute] = None,
-        span_attributes: Optional[Union[SpanAttributes, Mapping[str, Any]]] = None,
-        start_time: Optional[float] = None,
-        set_current: Optional[bool] = None,
-        parent: Optional[str] = None,
-        propagated_event: Optional[Dict[str, Any]] = None,
-        span_id: Optional[str] = None,
-        root_span_id: Optional[str] = None,
+        name: str | None = None,
+        type: SpanTypeAttribute | None = None,
+        span_attributes: SpanAttributes | Mapping[str, Any] | None = None,
+        start_time: float | None = None,
+        set_current: bool | None = None,
+        parent: str | None = None,
+        propagated_event: dict[str, Any] | None = None,
+        span_id: str | None = None,
+        root_span_id: str | None = None,
         lookup_span_parent: bool = True,
         **event: Any,
     ) -> Span:
@@ -5062,7 +5050,7 @@ class Logger(Exportable):
     def __enter__(self) -> "Logger":
         return self
 
-    def _get_link_base_url(self) -> Optional[str]:
+    def _get_link_base_url(self) -> str | None:
         """Return the base of link urls (e.g. https://braintrust.dev/app/my-org-name/) if we have the info
         otherwise return None.
         """
@@ -5098,11 +5086,11 @@ class ScoreSummary(SerializableDataClass):
     score: float
     """Average score across all examples."""
 
-    improvements: Optional[int]
+    improvements: int | None
     """Number of improvements in the score."""
-    regressions: Optional[int]
+    regressions: int | None
     """Number of regressions in the score."""
-    diff: Optional[float] = None
+    diff: float | None = None
     """Difference in score between the current and reference experiment."""
 
     def __str__(self):
@@ -5133,15 +5121,15 @@ class MetricSummary(SerializableDataClass):
     # Used to help with formatting
     _longest_metric_name: int
 
-    metric: Union[float, int]
+    metric: float | int
     """Average metric across all examples."""
     unit: str
     """Unit label for the metric."""
-    improvements: Optional[int]
+    improvements: int | None
     """Number of improvements in the metric."""
-    regressions: Optional[int]
+    regressions: int | None
     """Number of regressions in the metric."""
-    diff: Optional[float] = None
+    diff: float | None = None
     """Difference in metric between the current and reference experiment."""
 
     def __str__(self):
@@ -5167,21 +5155,21 @@ class ExperimentSummary(SerializableDataClass):
 
     project_name: str
     """Name of the project that the experiment belongs to."""
-    project_id: Optional[str]
+    project_id: str | None
     """ID of the project. May be `None` if the eval was run locally."""
-    experiment_id: Optional[str]
+    experiment_id: str | None
     """ID of the experiment. May be `None` if the eval was run locally."""
     experiment_name: str
     """Name of the experiment."""
-    project_url: Optional[str]
+    project_url: str | None
     """URL to the project's page in the Braintrust app."""
-    experiment_url: Optional[str]
+    experiment_url: str | None
     """URL to the experiment's page in the Braintrust app."""
-    comparison_experiment_name: Optional[str]
+    comparison_experiment_name: str | None
     """The experiment scores are baselined against."""
-    scores: Dict[str, ScoreSummary]
+    scores: dict[str, ScoreSummary]
     """Summary of the experiment's scores."""
-    metrics: Dict[str, MetricSummary]
+    metrics: dict[str, MetricSummary]
     """Summary of the experiment's metrics."""
 
     def __str__(self):
@@ -5230,7 +5218,7 @@ class DatasetSummary(SerializableDataClass):
     """URL to the project's page in the Braintrust app."""
     dataset_url: str
     """URL to the experiment's page in the Braintrust app."""
-    data_summary: Optional[DataSummary]
+    data_summary: DataSummary | None
     """Summary of the dataset's data."""
 
     def __str__(self):
@@ -5245,7 +5233,8 @@ class DatasetSummary(SerializableDataClass):
 
 
 class TracedThreadPoolExecutor(concurrent.futures.ThreadPoolExecutor):
-    # Returns Any because Future is not generic in Python 3.8.
+    # Returns Any because Future[T] generic typing was stabilized in Python 3.9,
+    # but we maintain compatibility with older type checkers.
     def submit(self, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
         # Capture all current context variables
         context = contextvars.copy_context()
@@ -5257,7 +5246,7 @@ class TracedThreadPoolExecutor(concurrent.futures.ThreadPoolExecutor):
         return super().submit(wrapped_fn, *args, **kwargs)
 
 
-def get_prompt_versions(project_id: str, prompt_id: str) -> List[str]:
+def get_prompt_versions(project_id: str, prompt_id: str) -> list[str]:
     """
     Get the versions for a specific prompt.
 
@@ -5317,13 +5306,13 @@ def get_prompt_versions(project_id: str, prompt_id: str) -> List[str]:
     ]
 
 
-def _get_app_url(app_url: Optional[str] = None) -> str:
+def _get_app_url(app_url: str | None = None) -> str:
     if app_url:
         return app_url
     return os.getenv("BRAINTRUST_APP_URL", DEFAULT_APP_URL)
 
 
-def _get_org_name(org_name: Optional[str] = None) -> Optional[str]:
+def _get_org_name(org_name: str | None = None) -> str | None:
     if org_name:
         return org_name
     return os.getenv("BRAINTRUST_ORG_NAME")