opik 2.2.76__tar.gz → 2.2.78__tar.gz

{opik-2.2.76/src/opik.egg-info → opik-2.2.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opik
-Version: 2.2.76
+Version: 2.2.78
 Summary: Comet tool for logging and evaluating LLM traces
 Home-page: https://www.comet.com
 Author: Comet ML Inc.

{opik-2.2.76 → opik-2.2.78}/src/opik/api_objects/constants.py

@@ -47,6 +47,20 @@ DATASET_ITEMS_READ_MAX_THREADS = 32
 # per worker), so an unbounded value authorises an unbounded resident bound.
 DATASET_ITEMS_WRITE_MAX_THREADS = 32
 
+# Page size for the experiment Compare-view read behind Experiment.get_items().
+# Counts dataset-item rows, the unit the endpoint pages by: a row carries one
+# experiment item per experiment id in the request, so a multi-experiment read
+# yields more items than this. The read is round-trip bound rather than payload
+# bound -- per-page latency is close to flat across sizes -- so the page count
+# is what this trades against per-response size. Same value as the dataset read's
+# batch size, so the two reads page at one size.
+EXPERIMENT_ITEMS_READ_PAGE_SIZE = DATASET_STREAM_BATCH_SIZE
+# Ceiling on that page size, matching the dataset read's own chunk ceiling so
+# one knob does not authorise a much larger response than the other. The backend
+# endpoint declares @Min(1) and no @Max, so this bounds a single response for
+# the caller rather than mirroring a server limit.
+EXPERIMENT_ITEMS_READ_MAX_PAGE_SIZE = DATASET_ITEMS_READ_MAX_CHUNK_SIZE
+
 # Parallel dataset insert requires a backend that serializes concurrent dataset
 # version writes. On backends older than this version, concurrent batches
 # sharing one batch_group_id raced and could 500 or silently drop rows; 2.2.8 is

{opik-2.2.76 → opik-2.2.78}/src/opik/api_objects/experiment/experiment.py

@@ -22,7 +22,7 @@ from opik.message_processing import messages, streamer
 from opik.rest_api import client as rest_api_client
 from opik.rest_api import types as rest_api_types
 from . import bulk_converters, bulk_item, experiment_item, experiments_client
-from .. import constants, helpers, rest_helpers, streaming_upload
+from .. import constants, helpers, rest_helpers, streaming_upload, validation_helpers
 from ...api_objects.prompt import base_prompt
 from ...rest_api.core.api_error import ApiError
 from ...rest_client_configurator import retry_decorator
@@ -681,6 +681,9 @@ class Experiment:
         self,
         max_results: Optional[int] = 10000,
         truncate: bool = False,
+        *,
+        page_size: int = constants.EXPERIMENT_ITEMS_READ_PAGE_SIZE,
+        num_threads: int = constants.DATASET_ITEMS_READ_NUM_THREADS,
     ) -> List[experiment_item.ExperimentItemContent]:
         """
         Retrieves and returns a list of experiment items for this experiment.
@@ -688,10 +691,34 @@ class Experiment:
         Args:
             max_results: Maximum number of experiment items to retrieve. Defaults to 10000 if not specified.
             truncate: Whether to truncate the items returned by the backend. Defaults to False.
+            page_size: Number of dataset items requested per page. Must be a
+                positive integer not exceeding
+                ``constants.EXPERIMENT_ITEMS_READ_MAX_PAGE_SIZE``. The read is
+                round-trip bound, so this mostly trades request count against
+                per-request size; lower it only if the backend struggles with
+                the default response size.
+            num_threads: Number of pages fetched concurrently after the first
+                one, which is read on its own to learn how many pages there are.
+                Must be a positive integer not exceeding
+                ``constants.DATASET_ITEMS_READ_MAX_THREADS``. Pass ``1`` to read
+                sequentially.
 
         Returns:
             List of ExperimentItemContent objects for this experiment.
+
+        Raises:
+            ValueError: If ``page_size`` is not a positive integer or exceeds
+                ``constants.EXPERIMENT_ITEMS_READ_MAX_PAGE_SIZE``, or if
+                ``num_threads`` is not a positive integer or exceeds
+                ``constants.DATASET_ITEMS_READ_MAX_THREADS``.
         """
+        validation_helpers.validate_bounded_positive_int(
+            page_size, "page_size", constants.EXPERIMENT_ITEMS_READ_MAX_PAGE_SIZE
+        )
+        validation_helpers.validate_bounded_positive_int(
+            num_threads, "num_threads", constants.DATASET_ITEMS_READ_MAX_THREADS
+        )
+
         if max_results is None:
             max_results = 10000  # TODO: remove this once we have a proper way to get all experiment items
 
@@ -701,6 +728,8 @@ class Experiment:
             truncate=truncate,
             max_results=max_results,
             project_name=self._project_name,
+            page_size=page_size,
+            num_threads=num_threads,
         )
 
     def log_experiment_scores(

opik-2.2.78/src/opik/api_objects/experiment/experiment_item.py

@@ -0,0 +1,232 @@
+import dataclasses
+
+from typing import Dict, Any, List, Optional, Type, TypeVar
+from opik import exceptions
+from opik.types import FeedbackScoreDict
+from opik.rest_api.types import experiment_item_compare
+
+AssertionResultDict = Dict[str, Any]
+
+T = TypeVar("T")
+
+
+def require_json_type(value: Any, expected: Type[T], what: str) -> T:
+    """``value`` when it has the shape the Compare schema declares, else raise.
+
+    The read parses the endpoint's JSON itself, so nothing re-derives the schema the
+    generated models used to enforce. Without this, a field the backend sent with the
+    wrong shape either surfaces as an ``AttributeError`` from deep inside the parse or,
+    worse, parses silently: ``list()`` over a dict yields its keys and over a string
+    yields its characters, which would turn a malformed ``assertion_results`` into
+    plausible-looking nonsense rather than an error.
+    """
+    if not isinstance(value, expected):
+        raise exceptions.OpikException(
+            f"The experiment Compare response is malformed: {what} is a "
+            f"{type(value).__name__}, not a {expected.__name__}."
+        )
+    return value
+
+
+def optional_json_list(
+    value: Any, what: str, entry_type: Optional[type] = None
+) -> List[Any]:
+    """``value`` as a list, an absent or null field reading as an empty one.
+
+    Spelled out rather than ``value or []``, which defaults on every falsy value: ``""``,
+    ``0`` and ``False`` are not lists, and a field carrying one of them means the
+    response is malformed, not that the list is empty. Only an absent key and an
+    explicit ``null`` are the empty list.
+
+    ``entry_type`` checks the entries too. A list of the right shape can still hold
+    entries of the wrong one -- ``[null]`` is the shape to expect, since the backend
+    omits a score rather than nulling it -- and the generated models rejected those as
+    firmly as they rejected the outer list.
+    """
+    if value is None:
+        return []
+    entries = require_json_type(value, list, what)
+    if entry_type is not None:
+        for entry in entries:
+            require_json_type(entry, entry_type, f"an entry of {what}")
+    return entries
+
+
+def _require_leaf_type(value: Any, expected: Any, what: str) -> None:
+    """Check one leaf field of a Compare entry, when it is present and not null.
+
+    Applied to the record's own ``id`` / ``trace_id`` / ``dataset_item_id``, and to the
+    score and assertion leaves. Passing a value of the wrong type through is not inert:
+    ``passed`` is mapped onto a status with ``"passed" if passed else "failed"``, where
+    the string ``"false"`` is truthy and records a failed assertion as passed; an
+    assertion's ``value`` becomes the ``Required[str]`` ``name`` of an ingested
+    assertion; and a score ``value`` is declared ``float`` and aggregated over.
+    Re-deriving the *rest* of the schema per node is the cost this read exists to
+    avoid, and this stops short of it.
+
+    ``input`` and ``output`` are deliberately **not** checked, and this is not an
+    oversight: ``JsonListStringCompare`` is ``Union[Dict, List[Dict], str]``, so the
+    API permits a string or a list where ``dataset_item_data`` and
+    ``evaluation_task_output`` are annotated ``Optional[Dict[str, Any]]``. The
+    annotation is narrower than the wire contract -- a discrepancy that predates this
+    read -- so enforcing ``dict`` here would reject responses the backend is entitled
+    to send.
+
+    Absence stays permissive -- an omitted or ``null`` field is what the backend sends
+    for a missing score, reason or verdict, and rejecting it would fail reads that work
+    today. Only a present value of the wrong type is an error.
+
+    ``bool`` is excluded from the numeric check: it is a subclass of ``int``, so
+    ``"value": true`` would otherwise pass as a score of 1.
+    """
+    if value is None:
+        return
+    if expected is not bool and isinstance(value, bool):
+        pass  # fall through to the failure below
+    elif isinstance(value, expected):
+        return
+    names = (
+        expected.__name__
+        if isinstance(expected, type)
+        else " or ".join(t.__name__ for t in expected)
+    )
+    raise exceptions.OpikException(
+        f"The experiment Compare response is malformed: {what} is a "
+        f"{type(value).__name__}, not {names}."
+    )
+
+
+@dataclasses.dataclass
+class ExperimentItemReferences:
+    dataset_item_id: str
+    trace_id: str
+    project_name: Optional[str] = None
+    execution_policy: Optional[Dict[str, Any]] = None
+
+
+@dataclasses.dataclass
+class ExperimentItemContent:
+    id: str
+    dataset_item_id: str
+    trace_id: str
+    dataset_item_data: Optional[Dict[str, Any]]
+    evaluation_task_output: Optional[Dict[str, Any]]
+    feedback_scores: List[FeedbackScoreDict]
+    assertion_results: List[AssertionResultDict] = dataclasses.field(
+        default_factory=list
+    )
+
+    @classmethod
+    def from_compare_dict(
+        cls,
+        value: Dict[str, Any],
+        dataset_item_data: Optional[Dict[str, Any]] = None,
+    ) -> "ExperimentItemContent":
+        """Build from the endpoint's own JSON, skipping the generated REST models.
+
+        Parsing a page into those models re-derives type hints per node, which costs
+        more than the request itself on a large experiment; the dataset read hands back
+        plain dicts for the same reason.
+        """
+        require_json_type(value, dict, "an `experiment_items` entry")
+        feedback_scores: List[FeedbackScoreDict] = []
+        for score in optional_json_list(
+            value.get("feedback_scores"), "`feedback_scores`", entry_type=dict
+        ):
+            _require_leaf_type(
+                score.get("value"), (int, float), "a `feedback_scores` entry's `value`"
+            )
+            for key in ("category_name", "reason"):
+                _require_leaf_type(
+                    score.get(key), str, f"a `feedback_scores` entry's `{key}`"
+                )
+            # `name` is the one leaf where absence is malformed rather than empty: it
+            # is required and `@NotBlank` on the backend, required on the Compare
+            # model, and `Required[str]` on `FeedbackScoreDict`.
+            name = score.get("name")
+            _require_leaf_type(name, str, "a `feedback_scores` entry's `name`")
+            if name is None or not name.strip():
+                raise exceptions.OpikException(
+                    "The experiment Compare response is malformed: a "
+                    "`feedback_scores` entry's `name` is missing or blank, and a "
+                    "score name is required."
+                )
+            feedback_scores.append(
+                {
+                    "category_name": score.get("category_name"),
+                    "name": score.get("name"),
+                    "reason": score.get("reason"),
+                    "value": score.get("value"),
+                }
+            )
+
+        assertion_results: List[AssertionResultDict] = []
+        for result in optional_json_list(
+            value.get("assertion_results"), "`assertion_results`", entry_type=dict
+        ):
+            _require_leaf_type(
+                result.get("passed"), bool, "an `assertion_results` entry's `passed`"
+            )
+            for key in ("value", "reason"):
+                _require_leaf_type(
+                    result.get(key), str, f"an `assertion_results` entry's `{key}`"
+                )
+            assertion_results.append(result)
+
+        # Indexing above already fails a page that omits these; this adds the type,
+        # since all three are `str` on the record they build.
+        for key in ("id", "trace_id", "dataset_item_id"):
+            _require_leaf_type(value[key], str, f"an experiment item's `{key}`")
+
+        return cls(
+            # Indexed, not `.get`: a page missing these is a broken response, and a
+            # record built around None would only fail further away.
+            id=value["id"],
+            trace_id=value["trace_id"],
+            dataset_item_id=value["dataset_item_id"],
+            dataset_item_data=dataset_item_data
+            if dataset_item_data
+            else value.get("input"),
+            evaluation_task_output=value.get("output"),
+            feedback_scores=feedback_scores,
+            assertion_results=assertion_results,
+        )
+
+    @classmethod
+    def from_rest_experiment_item_compare(
+        cls,
+        value: experiment_item_compare.ExperimentItemCompare,
+        dataset_item_data: Optional[Dict[str, Any]] = None,
+    ) -> "ExperimentItemContent":
+        if value.feedback_scores is None:
+            feedback_scores: List[FeedbackScoreDict] = []
+        else:
+            feedback_scores = [
+                {
+                    "category_name": rest_feedback_score.category_name,
+                    "name": rest_feedback_score.name,
+                    "reason": rest_feedback_score.reason,
+                    "value": rest_feedback_score.value,
+                }
+                for rest_feedback_score in value.feedback_scores
+            ]
+
+        if value.assertion_results is None:
+            assertion_results: List[AssertionResultDict] = []
+        else:
+            assertion_results = [
+                ar
+                if isinstance(ar, dict)
+                else {"value": ar.value, "passed": ar.passed, "reason": ar.reason}
+                for ar in value.assertion_results
+            ]
+
+        return ExperimentItemContent(
+            id=value.id,
+            trace_id=value.trace_id,
+            dataset_item_id=value.dataset_item_id,
+            dataset_item_data=dataset_item_data if dataset_item_data else value.input,
+            evaluation_task_output=value.output,
+            feedback_scores=feedback_scores,
+            assertion_results=assertion_results,
+        )

{opik-2.2.76 → opik-2.2.78}/src/opik/api_objects/experiment/experiments_client.py

@@ -2,7 +2,7 @@ import json
 from typing import List, Optional
 
 from . import rest_operations, experiment_item
-from .. import opik_query_language
+from .. import constants, opik_query_language, validation_helpers
 from ...rest_api import client as rest_api_client
 
 
@@ -20,6 +20,9 @@ class ExperimentsClient:
         max_results: int = 1000,
         filter_string: Optional[str] = None,
         project_name: Optional[str] = None,
+        *,
+        page_size: int = constants.EXPERIMENT_ITEMS_READ_PAGE_SIZE,
+        num_threads: int = constants.DATASET_ITEMS_READ_NUM_THREADS,
     ) -> List[experiment_item.ExperimentItemContent]:
         """
         Find experiment items associated with a specific dataset among a list of experiments.
@@ -37,10 +40,32 @@ class ExperimentsClient:
                 or metadata. Defaults to True.
             max_results: Maximum number of results to return. Defaults to 1000.
             project_name: Optional project name to associate with the query. If not provided, the default project will be used.
+            page_size: Number of dataset items requested per page. Must be a
+                positive integer not exceeding
+                ``constants.EXPERIMENT_ITEMS_READ_MAX_PAGE_SIZE``. Trades request
+                count against per-request size; the read is round-trip bound, so
+                lowering it is slower.
+            num_threads: Number of pages fetched concurrently after the first
+                one. Must be a positive integer not exceeding
+                ``constants.DATASET_ITEMS_READ_MAX_THREADS``. Pass ``1`` to read
+                sequentially.
 
         Returns:
             A list of experiment item content objects that match the criteria.
+
+        Raises:
+            ValueError: If ``page_size`` is not a positive integer or exceeds
+                ``constants.EXPERIMENT_ITEMS_READ_MAX_PAGE_SIZE``, or if
+                ``num_threads`` is not a positive integer or exceeds
+                ``constants.DATASET_ITEMS_READ_MAX_THREADS``.
         """
+        validation_helpers.validate_bounded_positive_int(
+            page_size, "page_size", constants.EXPERIMENT_ITEMS_READ_MAX_PAGE_SIZE
+        )
+        validation_helpers.validate_bounded_positive_int(
+            num_threads, "num_threads", constants.DATASET_ITEMS_READ_MAX_THREADS
+        )
+
         # prepare filter expression
         if filter_string is not None:
             filter_expression = json.dumps(
@@ -63,4 +88,6 @@ class ExperimentsClient:
             max_results=max_results,
             truncate=truncate,
             filter_expression=filter_expression,
+            page_size=page_size,
+            num_threads=num_threads,
         )

opik-2.2.78/src/opik/api_objects/experiment/rest_operations.py

@@ -0,0 +1,251 @@
+import json
+import math
+from concurrent import futures
+from typing import Any, Dict, List, Optional
+
+from . import experiment_item
+from .. import constants, rest_stream_parser
+from ... import exceptions, json_helpers, rest_api
+from ...rest_api.core.api_error import ApiError
+from ...rest_api.core.jsonable_encoder import jsonable_encoder
+from ...rest_api.types import experiment_public
+
+
+def get_experiment_data_by_name(
+    rest_client: rest_api.OpikApi,
+    name: str,
+    project_name: Optional[str],
+) -> experiment_public.ExperimentPublic:
+    # TODO: this method is deprecated and should be removed after
+    #  deprecated Opik.get_experiment_by_name() will be removed.
+    #  This function should not be used anywhere else except for deprecated logic as it is confusing and misleading
+
+    experiments = get_experiments_data_by_name(
+        rest_client, name, project_name=project_name
+    )
+    for experiment in experiments:
+        if experiment.name == name:
+            return experiment
+
+    raise exceptions.ExperimentNotFound(f"No experiment found with the name '{name}'.")
+
+
+def get_experiments_data_by_name(
+    rest_client: rest_api.OpikApi,
+    name: str,
+    project_name: Optional[str],
+    max_results: Optional[int] = None,
+) -> List[experiment_public.ExperimentPublic]:
+    experiments = rest_stream_parser.read_and_parse_full_stream(
+        read_source=lambda current_batch_size,
+        last_retrieved_id: rest_client.experiments.stream_experiments(
+            name=name,
+            limit=current_batch_size,
+            last_retrieved_id=last_retrieved_id,
+            project_name=project_name,
+        ),
+        max_results=max_results,
+        parsed_item_class=experiment_public.ExperimentPublic,
+    )
+
+    if len(experiments) == 0:
+        raise exceptions.ExperimentNotFound(
+            f"No experiment(s) found with the name '{name}'."
+        )
+
+    return experiments
+
+
+def find_experiment_items_for_dataset(
+    rest_client: rest_api.OpikApi,
+    dataset_id: str,
+    experiment_ids: List[str],
+    max_results: int,
+    truncate: bool,
+    filter_expression: Optional[str] = None,
+    page_size: int = constants.EXPERIMENT_ITEMS_READ_PAGE_SIZE,
+    num_threads: int = constants.DATASET_ITEMS_READ_NUM_THREADS,
+) -> List[experiment_item.ExperimentItemContent]:
+    # The sequential read this replaced never issued a request for a non-positive
+    # limit -- its `while len(collected) < max_results` was false on entry. Reading
+    # page 1 before the limit is consulted would turn that into one Compare request,
+    # and an `ApiError` where callers used to get `[]`.
+    if max_results <= 0:
+        return []
+
+    experiment_ids_json = json.dumps(experiment_ids)
+
+    def fetch_page(page_number: int) -> Dict[str, Any]:
+        return _fetch_page_json(
+            rest_client=rest_client,
+            dataset_id=dataset_id,
+            page_number=page_number,
+            page_size=page_size,
+            experiment_ids_json=experiment_ids_json,
+            truncate=truncate,
+            filter_expression=filter_expression,
+        )
+
+    collected_items: List[experiment_item.ExperimentItemContent] = []
+
+    # The first page is read on its own because its `total` is what bounds every
+    # wave after it.
+    first_page = fetch_page(1)
+    _collect_page(first_page, collected_items, max_results)
+
+    if not first_page.get("content"):
+        return collected_items
+
+    # A `total` the backend omits or sends malformed leaves the page count
+    # unknown, and the read falls back to walking until an empty page.
+    total = first_page.get("total")
+    last_page = (
+        max(1, math.ceil(total / page_size))
+        if isinstance(total, int) and not isinstance(total, bool) and total >= 0
+        else None
+    )
+
+    next_page = 2
+    while len(collected_items) < max_results:
+        if last_page is not None and next_page > last_page:
+            break
+
+        # Pages are dataset-item rows, `max_results` counts experiment items, and a
+        # row carries one item per experiment id -- so this is the page count only
+        # for the common single-id read. Either way it costs requests, not
+        # correctness: a denser page overshoots and the extra pages are trimmed to
+        # `max_results`, a sparser one undershoots and takes another wave. The exact
+        # count needs the items-per-row ratio, which is not known until pages arrive.
+        wave_size = math.ceil((max_results - len(collected_items)) / page_size)
+        if last_page is not None:
+            wave_size = min(wave_size, last_page - next_page + 1)
+        wave_size = min(wave_size, num_threads)
+
+        page_numbers = list(range(next_page, next_page + wave_size))
+        next_page += wave_size
+
+        if wave_size == 1:
+            pages = [fetch_page(page_numbers[0])]
+        else:
+            with futures.ThreadPoolExecutor(
+                max_workers=wave_size,
+                thread_name_prefix="opik_experiment_items_read",
+            ) as pool:
+                pages = list(pool.map(fetch_page, page_numbers))
+
+        for page in pages:
+            # Pages are consumed in order, so an empty one ends the read exactly
+            # where a sequential walk would have stopped.
+            if not page.get("content"):
+                return collected_items
+            _collect_page(page, collected_items, max_results)
+
+    return collected_items
+
+
+def http_client(rest_client: rest_api.OpikApi) -> Any:
+    """The generated client's shared HTTP helper.
+
+    It applies the base URL, the auth and workspace headers, the configured timeout
+    and the retry policy -- every generated endpoint reaches it through this same
+    private attribute. Named here once so a Fern regeneration that moves it fails with
+    this message instead of an AttributeError inside a page fetch, and so the one place
+    that has to change is this function.
+    """
+    httpx_client = getattr(
+        getattr(rest_client, "_client_wrapper", None), "httpx_client", None
+    )
+    if httpx_client is None:
+        raise exceptions.OpikException(
+            "The Opik REST client does not expose its HTTP client at "
+            "`_client_wrapper.httpx_client`. The generated client's layout has "
+            "changed and `opik.api_objects.experiment.rest_operations.http_client` "
+            "needs updating to match it."
+        )
+    return httpx_client
+
+
+def _fetch_page_json(
+    rest_client: rest_api.OpikApi,
+    dataset_id: str,
+    page_number: int,
+    page_size: int,
+    experiment_ids_json: str,
+    truncate: bool,
+    filter_expression: Optional[str],
+) -> Dict[str, Any]:
+    """One page of the Compare view as plain JSON.
+
+    Deliberately not the generated client: parsing a page into the REST models costs
+    more than fetching it -- on a 100,000-item read it was ~85% of the client time,
+    walking every node to re-derive type hints. The response shape is the same either
+    way, so the read stays a dict walk, as the dataset read already is.
+    """
+    response = http_client(rest_client).request(
+        f"v1/private/datasets/{jsonable_encoder(dataset_id)}/items/experiments/items",
+        method="GET",
+        params={
+            "page": page_number,
+            "size": page_size,
+            "experiment_ids": experiment_ids_json,
+            "filters": filter_expression,
+            "truncate": truncate,
+        },
+    )
+    if not 200 <= response.status_code < 300:
+        # `body` is the parsed payload where the backend sent JSON and the raw text
+        # where it did not, which is what the generated client hands back and what
+        # readers of `ApiError.body` already expect.
+        try:
+            body: Any = json_helpers.loads(response.content)
+        except ValueError:
+            body = response.text
+        raise ApiError(
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            body=body,
+        )
+
+    try:
+        page = json_helpers.loads(response.content)
+    except ValueError:
+        # The generated endpoint decodes the 2xx body inside the same `try` as the
+        # error one, so an undecodable success body reaches callers as an `ApiError`
+        # carrying the raw text, not as a decoder error. Keep that contract.
+        raise ApiError(
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            body=response.text,
+        )
+    return experiment_item.require_json_type(page, dict, "the page")
+
+
+def _collect_page(
+    page: Dict[str, Any],
+    collected_items: List[experiment_item.ExperimentItemContent],
+    max_results: int,
+) -> None:
+    """Append one page's experiment items, stopping at ``max_results``."""
+    headroom = max_results - len(collected_items)
+    content = experiment_item.optional_json_list(page.get("content"), "`content`")
+    if headroom <= 0 or not content:
+        return
+
+    page_items = []
+    for dataset_item in content:
+        experiment_item.require_json_type(dataset_item, dict, "a `content` entry")
+        for experiment_item_compare in experiment_item.optional_json_list(
+            dataset_item.get("experiment_items"), "`experiment_items`"
+        ):
+            dataset_item_data = dataset_item.get("data")
+            if dataset_item_data is not None:
+                experiment_item.require_json_type(dataset_item_data, dict, "`data`")
+                dataset_item_data.update({"id": dataset_item.get("id")})
+            page_items.append(
+                experiment_item.ExperimentItemContent.from_compare_dict(
+                    value=experiment_item_compare,
+                    dataset_item_data=dataset_item_data,
+                )
+            )
+
+    collected_items.extend(page_items[:headroom])

{opik-2.2.76 → opik-2.2.78}/src/opik/api_objects/validation_helpers.py

@@ -87,3 +87,13 @@ def validate_feedback_score(
         return None
 
     return cast(BatchFeedbackScoreDict, feedback_score)
+
+
+def validate_bounded_positive_int(
+    value: Any, name: str, maximum: Optional[int] = None
+) -> None:
+    """Raise ``ValueError`` unless ``value`` is a positive int within ``maximum``."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ValueError(f"{name} must be a positive integer")
+    if maximum is not None and value > maximum:
+        raise ValueError(f"{name} must not exceed {maximum}, got {value}")

{opik-2.2.76 → opik-2.2.78}/src/opik/cli/migrate/datasets/experiments.py

@@ -738,12 +738,14 @@ def _read_source_experiment_items(
 
     Routes through the high-level
     ``api_objects.experiment.rest_operations.find_experiment_items_for_dataset``
-    helper, which paginates
-    ``datasets.find_dataset_items_with_experiment_items`` internally
-    (PAGE_SIZE=100), flattens each page's per-dataset-item
-    ``experiment_items`` list, and returns ``ExperimentItemContent``
-    dataclasses with ``assertion_results`` already normalized to
-    ``List[AssertionResultDict]``.
+    helper, which pages the Compare view
+    (``constants.EXPERIMENT_ITEMS_READ_PAGE_SIZE`` items per page), fetching
+    pages concurrently but returning them in page order, bounded by the first
+    page's ``total`` and walking to an empty page when that is unusable. It
+    flattens each page's per-dataset-item ``experiment_items`` list and returns
+    ``ExperimentItemContent`` dataclasses with ``assertion_results`` already
+    normalized to ``List[AssertionResultDict]``. How it reaches the endpoint is
+    the helper's own business and documented there.
 
     Compare view (vs. the Public ``stream_experiment_items``) is the
     correct read shape here because only Compare surfaces