arize-phoenix 3.16.1__py3-none-any.whl → 7.7.1__py3-none-any.whl

phoenix/core/model_schema_adapter.py

@@ -1,69 +1,72 @@
+from collections.abc import Iterable, Sized
 from itertools import chain
 from operator import itemgetter
-from typing import Dict, Iterable, List, Optional, Sized, Tuple, Union
+from typing import Optional, Union
 
 import pandas as pd
 from pandas.api.types import is_object_dtype
 from typing_extensions import TypeAlias, TypeGuard
 
-from phoenix import Dataset, EmbeddingColumnNames
 from phoenix.core.model import _get_embedding_dimensions
 from phoenix.core.model_schema import Embedding, Model, RetrievalEmbedding, Schema
-from phoenix.datasets.schema import RetrievalEmbeddingColumnNames
-from phoenix.datasets.schema import Schema as DatasetSchema
+from phoenix.inferences.inferences import Inferences
+from phoenix.inferences.schema import EmbeddingColumnNames, RetrievalEmbeddingColumnNames
+from phoenix.inferences.schema import Schema as InferencesSchema
 
-DatasetName: TypeAlias = str
+InferencesName: TypeAlias = str
 ColumnName: TypeAlias = str
 DisplayName: TypeAlias = str
 
 
-def create_model_from_datasets(*datasets: Optional[Dataset]) -> Model:
+def create_model_from_inferences(*inference_sets: Optional[Inferences]) -> Model:
     # TODO: move this validation into model_schema.Model.
-    if len(datasets) > 1 and datasets[0] is not None:
+    if len(inference_sets) > 1 and inference_sets[0] is not None:
         # Check that for each embedding dimension all vectors
-        # have the same length between datasets.
-        _ = _get_embedding_dimensions(datasets[0], datasets[1])
-
-    named_dataframes: List[Tuple[DatasetName, pd.DataFrame]] = []
-    prediction_ids: List[ColumnName] = []
-    timestamps: List[ColumnName] = []
-    prediction_labels: List[ColumnName] = []
-    prediction_scores: List[ColumnName] = []
-    actual_labels: List[ColumnName] = []
-    actual_scores: List[ColumnName] = []
-    features: List[ColumnName] = []
-    tags: List[ColumnName] = []
-    embeddings: Dict[DisplayName, EmbeddingColumnNames] = {}
-    prompts: List[EmbeddingColumnNames] = []
-    responses: List[Union[str, EmbeddingColumnNames]] = []
-
-    for dataset in filter(_is_dataset, datasets):
-        df = dataset.dataframe
+        # have the same length between inferences.
+        _ = _get_embedding_dimensions(inference_sets[0], inference_sets[1])
+
+    named_dataframes: list[tuple[InferencesName, pd.DataFrame]] = []
+    prediction_ids: list[ColumnName] = []
+    timestamps: list[ColumnName] = []
+    prediction_labels: list[ColumnName] = []
+    prediction_scores: list[ColumnName] = []
+    actual_labels: list[ColumnName] = []
+    actual_scores: list[ColumnName] = []
+    features: list[ColumnName] = []
+    tags: list[ColumnName] = []
+    embeddings: dict[DisplayName, EmbeddingColumnNames] = {}
+    prompts: list[EmbeddingColumnNames] = []
+    responses: list[Union[str, EmbeddingColumnNames]] = []
+
+    for inferences in filter(_is_inferences, inference_sets):
+        df = inferences.dataframe
         # Coerce string column names at run time.
         df = df.set_axis(
             map(str, df.columns),
             axis=1,
         )
-        named_dataframes.append((dataset.name, df))
-        dataset_schema = dataset.schema if dataset.schema is not None else DatasetSchema()
+        named_dataframes.append((inferences.name, df))
+        inferences_schema = (
+            inferences.schema if inferences.schema is not None else InferencesSchema()
+        )
         for display_name, embedding in (
-            dataset_schema.embedding_feature_column_names or {}
+            inferences_schema.embedding_feature_column_names or {}
         ).items():
             if display_name not in embeddings:
                 embeddings[display_name] = embedding
-        if dataset_schema.prompt_column_names is not None:
-            prompts.append(dataset_schema.prompt_column_names)
-        if dataset_schema.response_column_names is not None:
-            responses.append(dataset_schema.response_column_names)
+        if inferences_schema.prompt_column_names is not None:
+            prompts.append(inferences_schema.prompt_column_names)
+        if inferences_schema.response_column_names is not None:
+            responses.append(inferences_schema.response_column_names)
         for source, sink in (
-            ([dataset_schema.prediction_id_column_name], prediction_ids),
-            ([dataset_schema.timestamp_column_name], timestamps),
-            ([dataset_schema.prediction_label_column_name], prediction_labels),
-            ([dataset_schema.prediction_score_column_name], prediction_scores),
-            ([dataset_schema.actual_label_column_name], actual_labels),
-            ([dataset_schema.actual_score_column_name], actual_scores),
-            (dataset_schema.feature_column_names or (), features),
-            (dataset_schema.tag_column_names or (), tags),
+            ([inferences_schema.prediction_id_column_name], prediction_ids),
+            ([inferences_schema.timestamp_column_name], timestamps),
+            ([inferences_schema.prediction_label_column_name], prediction_labels),
+            ([inferences_schema.prediction_score_column_name], prediction_scores),
+            ([inferences_schema.actual_label_column_name], actual_labels),
+            ([inferences_schema.actual_score_column_name], actual_scores),
+            (inferences_schema.feature_column_names or (), features),
+            (inferences_schema.tag_column_names or (), tags),
         ):
             # Coerce None to "" to simplify type checks.
             sink.extend(map(lambda s: "" if s is None else str(s), source))
@@ -132,8 +135,8 @@ def create_model_from_datasets(*datasets: Optional[Dataset]) -> Model:
     )
 
 
-def _is_dataset(obj: Optional[Dataset]) -> TypeGuard[Dataset]:
-    return type(obj) is Dataset
+def _is_inferences(obj: Optional[Inferences]) -> TypeGuard[Inferences]:
+    return type(obj) is Inferences
 
 
 def _take_first_str(iterator: Iterable[str]) -> str:
@@ -182,14 +185,14 @@ def _translate_prompt_embedding(
 def _split_vectors_vs_scalars(
     names: Iterable[str],
     *dataframes: pd.DataFrame,
-) -> Tuple[List[str], List[Embedding]]:
+) -> tuple[list[str], list[Embedding]]:
     """A best-effort attempt at separating vector columns from scalar columns
     by examining the first non-null item of the column from each dataframe. If
     any item is `Iterable` and `Sized`, but not `str`, then the column is
     returned as `Embedding`, else it's returned as scalar.
     """
-    scalars: List[str] = []
-    vectors: List[Embedding] = []
+    scalars: list[str] = []
+    vectors: list[Embedding] = []
     # convert to sets for a speedier lookup
     column_names = [set(df.columns) for df in dataframes]
     for name in names:

phoenix/datetime_utils.py

@@ -1,5 +1,5 @@
-from datetime import datetime, timedelta, timezone
-from typing import Any, Optional, Tuple, cast
+from datetime import datetime, timedelta, timezone, tzinfo
+from typing import Any, Optional, cast
 
 import pandas as pd
 import pytz
@@ -11,6 +11,27 @@ from pandas.core.dtypes.common import (
     is_object_dtype,
 )
 
+_LOCAL_TIMEZONE = datetime.now(timezone.utc).astimezone().tzinfo
+
+
+def local_now() -> datetime:
+    return datetime.now(timezone.utc).astimezone(tz=_LOCAL_TIMEZONE)
+
+
+def normalize_datetime(
+    dt: Optional[datetime],
+    tz: Optional[tzinfo] = None,
+) -> Optional[datetime]:
+    """
+    If the input datetime is timezone-naive, it is localized as local timezone
+    unless tzinfo is specified.
+    """
+    if not isinstance(dt, datetime):
+        return None
+    if dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
+        dt = dt.replace(tzinfo=tz if tz else _LOCAL_TIMEZONE)
+    return dt.astimezone(timezone.utc)
+
 
 def normalize_timestamps(
     timestamps: "pd.Series[Any]",
@@ -75,7 +96,7 @@ MINUTE_DATETIME_FORMAT = "%Y-%m-%dT%H:%M:00%z"
 def right_open_time_range(
     min_time: Optional[datetime],
     max_time: Optional[datetime],
-) -> Tuple[Optional[datetime], Optional[datetime]]:
+) -> tuple[Optional[datetime], Optional[datetime]]:
     """
     First adds one minute to `max_time`, because time intervals are right
     open and one minute is the smallest interval allowed, then rounds down

phoenix/db/README.md

@@ -0,0 +1,54 @@
+# Database
+
+This module is responsible for the database connection and the migrations.
+
+
+## Migrations
+
+All migrations are managed by Alembic. Migrations are applied to the database automatically when the application starts.
+
+
+### Manually Applying Migrations
+
+Sometimes, it's necessary to manually apply migrations, e.g., to recover from a failed migration. To manually apply migrations, you must first clone the Phoenix repository.
+
+```bash
+git clone https://github.com/Arize-ai/phoenix.git
+```
+
+Then navigate to the current directory.
+
+```bash
+cd phoenix/src/phoenix/db
+```
+
+If you are using a non-default SQL database URL (e.g., for running PostgreSQL), ensure your `PHOENIX_SQL_DATABASE_URL` is set. This is not needed if you are running Phoenix with the default SQLite URL.
+
+```bash
+export PHOENIX_SQL_DATABASE_URL=<sql-database-url>
+```
+
+
+To manually run up-migrations, run the following command:
+
+```bash
+alembic upgrade head
+```
+
+If the above command fails, it may be necessary to undo partially applied changes from a failed migration by first running down-migrations. This can be accomplished by identifying the ID of the migration revision you wish to return to. Revisions are defined [here](./migrations/versions/).
+
+⚠️ Running down-migrations can result in lost data. Only run down-migrations if you know what you are doing and consider backing up your database first. If you have any questions or doubts, contact the Phoenix team in the `#phoenix-support` channel of the [Arize AI Slack community](https://join.slack.com/t/arize-ai/shared_invite/zt-1px8dcmlf-fmThhDFD_V_48oU7ALan4Q) or via GitHub.
+
+```bash
+alembic downgrade <revision-id>
+```
+
+### Creating a Migration
+
+All migrations are stored in the `migrations` folder. To create a new migration, run the following command:
+
+```bash
+alembic revision -m "your_revision_name"
+```
+
+Then fill the migration file with the necessary changes.

phoenix/db/__init__.py

@@ -0,0 +1,4 @@
+from .engines import get_printable_db_url
+from .migrate import migrate
+
+__all__ = ["migrate", "get_printable_db_url"]

phoenix/db/alembic.ini

@@ -0,0 +1,85 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+# Note this is overridden in .migrate during programatic migrations
+script_location = migrations
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python>=3.9 or backports.zoneinfo library.
+# Any required deps can installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to migrations/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "version_path_separator" below.
+# version_locations = %(here)s/bar:%(here)s/bat:migrations/versions
+
+# version path separator; As mentioned above, this is the character used to split
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
+#
+# version_path_separator = :
+# version_path_separator = ;
+# version_path_separator = space
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# NB: This is commented out intentionally as it is dynamic
+# See migrations/env.py
+# sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the exec runner, execute a binary
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = %(here)s/.venv/bin/ruff
+# ruff.options = --fix REVISION_SCRIPT_FILENAME
+

phoenix/db/bulk_inserter.py

@@ -0,0 +1,294 @@
+import asyncio
+import logging
+from asyncio import Queue, as_completed
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterable
+from dataclasses import dataclass, field
+from functools import singledispatchmethod
+from itertools import islice
+from time import perf_counter
+from typing import Any, Optional, cast
+
+from typing_extensions import TypeAlias
+
+import phoenix.trace.v1 as pb
+from phoenix.db.insertion.constants import DEFAULT_RETRY_ALLOWANCE, DEFAULT_RETRY_DELAY_SEC
+from phoenix.db.insertion.document_annotation import DocumentAnnotationQueueInserter
+from phoenix.db.insertion.evaluation import (
+    InsertEvaluationError,
+    insert_evaluation,
+)
+from phoenix.db.insertion.helpers import DataManipulation, DataManipulationEvent
+from phoenix.db.insertion.span import SpanInsertionEvent, insert_span
+from phoenix.db.insertion.span_annotation import SpanAnnotationQueueInserter
+from phoenix.db.insertion.trace_annotation import TraceAnnotationQueueInserter
+from phoenix.db.insertion.types import Insertables, Precursors
+from phoenix.server.dml_event import DmlEvent, SpanInsertEvent
+from phoenix.server.types import CanPutItem, DbSessionFactory
+from phoenix.trace.schemas import Span
+
+logger = logging.getLogger(__name__)
+
+ProjectRowId: TypeAlias = int
+
+
+@dataclass(frozen=True)
+class TransactionResult:
+    updated_project_rowids: set[ProjectRowId] = field(default_factory=set)
+
+
+class BulkInserter:
+    def __init__(
+        self,
+        db: DbSessionFactory,
+        *,
+        event_queue: CanPutItem[DmlEvent],
+        initial_batch_of_spans: Optional[Iterable[tuple[Span, str]]] = None,
+        initial_batch_of_evaluations: Optional[Iterable[pb.Evaluation]] = None,
+        sleep: float = 0.1,
+        max_ops_per_transaction: int = 1000,
+        max_queue_size: int = 1000,
+        enable_prometheus: bool = False,
+        retry_delay_sec: float = DEFAULT_RETRY_DELAY_SEC,
+        retry_allowance: int = DEFAULT_RETRY_ALLOWANCE,
+    ) -> None:
+        """
+        :param db: A function to initiate a new database session.
+        :param initial_batch_of_spans: Initial batch of spans to insert.
+        :param sleep: The time to sleep between bulk insertions
+        :param max_ops_per_transaction: The maximum number of operations to dequeue from
+        the operations queue for each transaction.
+        :param max_queue_size: The maximum length of the operations queue.
+        :param enable_prometheus: Whether Prometheus is enabled.
+        """
+        self._db = db
+        self._running = False
+        self._sleep = sleep
+        self._max_ops_per_transaction = max_ops_per_transaction
+        self._operations: Optional[Queue[DataManipulation]] = None
+        self._max_queue_size = max_queue_size
+        self._spans: list[tuple[Span, str]] = (
+            [] if initial_batch_of_spans is None else list(initial_batch_of_spans)
+        )
+        self._evaluations: list[pb.Evaluation] = (
+            [] if initial_batch_of_evaluations is None else list(initial_batch_of_evaluations)
+        )
+        self._task: Optional[asyncio.Task[None]] = None
+        self._event_queue = event_queue
+        self._enable_prometheus = enable_prometheus
+        self._retry_delay_sec = retry_delay_sec
+        self._retry_allowance = retry_allowance
+        self._queue_inserters = _QueueInserters(db, self._retry_delay_sec, self._retry_allowance)
+
+    async def __aenter__(
+        self,
+    ) -> tuple[
+        Callable[[Any], Awaitable[None]],
+        Callable[[Span, str], Awaitable[None]],
+        Callable[[pb.Evaluation], Awaitable[None]],
+        Callable[[DataManipulation], None],
+    ]:
+        self._running = True
+        self._operations = Queue(maxsize=self._max_queue_size)
+        self._task = asyncio.create_task(self._bulk_insert())
+        return (
+            self._enqueue,
+            self._queue_span,
+            self._queue_evaluation,
+            self._enqueue_operation,
+        )
+
+    async def __aexit__(self, *args: Any) -> None:
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            self._task = None
+
+    async def _enqueue(self, *items: Any) -> None:
+        await self._queue_inserters.enqueue(*items)
+
+    def _enqueue_operation(self, operation: DataManipulation) -> None:
+        cast("Queue[DataManipulation]", self._operations).put_nowait(operation)
+
+    async def _queue_span(self, span: Span, project_name: str) -> None:
+        self._spans.append((span, project_name))
+
+    async def _queue_evaluation(self, evaluation: pb.Evaluation) -> None:
+        self._evaluations.append(evaluation)
+
+    async def _process_events(self, events: Iterable[Optional[DataManipulationEvent]]) -> None: ...
+
+    async def _bulk_insert(self) -> None:
+        assert isinstance(self._operations, Queue)
+        spans_buffer, evaluations_buffer = None, None
+        # start first insert immediately if the inserter has not run recently
+        while (
+            self._running
+            or not self._queue_inserters.empty
+            or not self._operations.empty()
+            or self._spans
+            or self._evaluations
+        ):
+            if (
+                self._queue_inserters.empty
+                and self._operations.empty()
+                and not self._spans
+                and not self._evaluations
+            ):
+                await asyncio.sleep(self._sleep)
+                continue
+            ops_remaining = self._max_ops_per_transaction
+            async with self._db() as session:
+                while ops_remaining and not self._operations.empty():
+                    ops_remaining -= 1
+                    op = await self._operations.get()
+                    try:
+                        async with session.begin_nested():
+                            await op(session)
+                    except Exception as e:
+                        if self._enable_prometheus:
+                            from phoenix.server.prometheus import BULK_LOADER_EXCEPTIONS
+
+                            BULK_LOADER_EXCEPTIONS.inc()
+                        logger.exception(str(e))
+            # It's important to grab the buffers at the same time so there's
+            # no race condition, since an eval insertion will fail if the span
+            # it references doesn't exist. Grabbing the eval buffer later may
+            # include an eval whose span is in the queue but missed being
+            # included in the span buffer that was grabbed previously.
+            if self._spans:
+                spans_buffer = self._spans
+                self._spans = []
+            if self._evaluations:
+                evaluations_buffer = self._evaluations
+                self._evaluations = []
+            # Spans should be inserted before the evaluations, since an evaluation
+            # insertion will fail if the span it references doesn't exist.
+            if spans_buffer:
+                await self._insert_spans(spans_buffer)
+                spans_buffer = None
+            if evaluations_buffer:
+                await self._insert_evaluations(evaluations_buffer)
+                evaluations_buffer = None
+            async for event in self._queue_inserters.insert():
+                self._event_queue.put(event)
+            await asyncio.sleep(self._sleep)
+
+    async def _insert_spans(self, spans: list[tuple[Span, str]]) -> None:
+        project_ids = set()
+        for i in range(0, len(spans), self._max_ops_per_transaction):
+            try:
+                start = perf_counter()
+                async with self._db() as session:
+                    for span, project_name in islice(spans, i, i + self._max_ops_per_transaction):
+                        if self._enable_prometheus:
+                            from phoenix.server.prometheus import BULK_LOADER_SPAN_INSERTIONS
+
+                            BULK_LOADER_SPAN_INSERTIONS.inc()
+                        result: Optional[SpanInsertionEvent] = None
+                        try:
+                            async with session.begin_nested():
+                                result = await insert_span(session, span, project_name)
+                        except Exception:
+                            if self._enable_prometheus:
+                                from phoenix.server.prometheus import BULK_LOADER_EXCEPTIONS
+
+                                BULK_LOADER_EXCEPTIONS.inc()
+                            logger.exception(
+                                f"Failed to insert span with span_id={span.context.span_id}"
+                            )
+                        if result is not None:
+                            project_ids.add(result.project_rowid)
+                if self._enable_prometheus:
+                    from phoenix.server.prometheus import BULK_LOADER_INSERTION_TIME
+
+                    BULK_LOADER_INSERTION_TIME.observe(perf_counter() - start)
+            except Exception:
+                if self._enable_prometheus:
+                    from phoenix.server.prometheus import BULK_LOADER_EXCEPTIONS
+
+                    BULK_LOADER_EXCEPTIONS.inc()
+                logger.exception("Failed to insert spans")
+        self._event_queue.put(SpanInsertEvent(tuple(project_ids)))
+
+    async def _insert_evaluations(self, evaluations: list[pb.Evaluation]) -> None:
+        for i in range(0, len(evaluations), self._max_ops_per_transaction):
+            try:
+                start = perf_counter()
+                async with self._db() as session:
+                    for evaluation in islice(evaluations, i, i + self._max_ops_per_transaction):
+                        if self._enable_prometheus:
+                            from phoenix.server.prometheus import BULK_LOADER_EVALUATION_INSERTIONS
+
+                            BULK_LOADER_EVALUATION_INSERTIONS.inc()
+                        try:
+                            async with session.begin_nested():
+                                await insert_evaluation(session, evaluation)
+                        except InsertEvaluationError as error:
+                            if self._enable_prometheus:
+                                from phoenix.server.prometheus import BULK_LOADER_EXCEPTIONS
+
+                                BULK_LOADER_EXCEPTIONS.inc()
+                            logger.exception(f"Failed to insert evaluation: {str(error)}")
+                if self._enable_prometheus:
+                    from phoenix.server.prometheus import BULK_LOADER_INSERTION_TIME
+
+                    BULK_LOADER_INSERTION_TIME.observe(perf_counter() - start)
+            except Exception:
+                if self._enable_prometheus:
+                    from phoenix.server.prometheus import BULK_LOADER_EXCEPTIONS
+
+                    BULK_LOADER_EXCEPTIONS.inc()
+                logger.exception("Failed to insert evaluations")
+
+
+class _QueueInserters:
+    def __init__(
+        self,
+        db: DbSessionFactory,
+        retry_delay_sec: float = DEFAULT_RETRY_DELAY_SEC,
+        retry_allowance: int = DEFAULT_RETRY_ALLOWANCE,
+    ) -> None:
+        self._db = db
+        args = (db, retry_delay_sec, retry_allowance)
+        self._span_annotations = SpanAnnotationQueueInserter(*args)
+        self._trace_annotations = TraceAnnotationQueueInserter(*args)
+        self._document_annotations = DocumentAnnotationQueueInserter(*args)
+        self._queues = (
+            self._span_annotations,
+            self._trace_annotations,
+            self._document_annotations,
+        )
+
+    async def insert(self) -> AsyncIterator[DmlEvent]:
+        if self.empty:
+            return
+        for coro in as_completed([q.insert() for q in self._queues if not q.empty]):
+            if events := cast(Optional[list[DmlEvent]], await coro):
+                for event in events:
+                    yield event
+
+    @property
+    def empty(self) -> bool:
+        return all(q.empty for q in self._queues)
+
+    async def enqueue(self, *items: Any) -> None:
+        for item in items:
+            await self._enqueue(item)
+
+    @singledispatchmethod
+    async def _enqueue(self, item: Any) -> None: ...
+
+    @_enqueue.register(Precursors.SpanAnnotation)
+    @_enqueue.register(Insertables.SpanAnnotation)
+    async def _(self, item: Precursors.SpanAnnotation) -> None:
+        await self._span_annotations.enqueue(item)
+
+    @_enqueue.register(Precursors.TraceAnnotation)
+    @_enqueue.register(Insertables.TraceAnnotation)
+    async def _(self, item: Precursors.TraceAnnotation) -> None:
+        await self._trace_annotations.enqueue(item)
+
+    @_enqueue.register(Precursors.DocumentAnnotation)
+    @_enqueue.register(Insertables.DocumentAnnotation)
+    async def _(self, item: Precursors.DocumentAnnotation) -> None:
+        await self._document_annotations.enqueue(item)