feat(platform): Add item filtering for fetching run results.

src/aignostics/platform/CLAUDE.md

@@ -793,7 +793,7 @@ def delete(self) -> None:
 - ✅ `Applications.list()` - Application list (5 min TTL)
 - ✅ `Applications.details()` - Application details (5 min TTL)
 - ✅ `Runs.details()` - Run details (15 sec TTL)
-- ✅ `Runs.results()` - Run results (15 sec TTL)
+- ✅ `Runs.results()` - Run results (15 sec TTL), supports `item_ids` and `external_ids` filters
 - ✅ `Runs.list()` - Run list (15 sec TTL)
 
 **Cache Bypass (NEW):**

src/aignostics/platform/resources/runs.py

@@ -202,17 +202,24 @@ def delete(self) -> None:
  )
  operation_cache_clear() # Clear all caches since we added a new run
 
- def results(self, nocache: bool = False) -> t.Iterator[ItemResultData]:
+ def results(
+ self,
+ nocache: bool = False,
+ item_ids: list[str] | None = None,
+ external_ids: list[str] | None = None,
+ ) -> t.Iterator[ItemResultData]:
  """Retrieves the results of all items in the run.
 
  Retries on network and server errors.
 
  Args:
  nocache (bool): If True, skip reading from cache and fetch fresh data from the API.
  The fresh result will still be cached for subsequent calls. Defaults to False.
+ item_ids (list[str] | None): Optional list of item IDs to filter results by.
+ external_ids (list[str] | None): Optional list of external IDs to filter results by.
 
  Returns:
-list[ItemResultData]: A list of item results.
+Iterator[ItemResultData]: An iterator over item results.
 
  Raises:
  Exception: If the API request fails.
@@ -237,7 +244,13 @@ def results_with_retry(run_id: str, **kwargs: object) -> list[ItemResultData]:
  )
  )
 
- return paginate(lambda **kwargs: results_with_retry(self.run_id, nocache=nocache, **kwargs))
+ filter_kwargs: dict[str, object] = {}
+ if item_ids:
+ filter_kwargs["item_id__in"] = item_ids
+ if external_ids:
+ filter_kwargs["external_id__in"] = external_ids
+
+ return paginate(lambda **kwargs: results_with_retry(self.run_id, nocache=nocache, **filter_kwargs, **kwargs))
 
  def download_to_folder( # noqa: C901
  self,

tests/aignostics/application/cli_test.py

@@ -20,6 +20,12 @@
 from tests.constants_test import (
  HETA_APPLICATION_ID,
  HETA_APPLICATION_VERSION,
+ SPOT_0_CRC32C,
+ SPOT_0_FILENAME,
+ SPOT_0_GS_URL,
+ SPOT_0_HEIGHT,
+ SPOT_0_RESOLUTION_MPP,
+ SPOT_0_WIDTH,
  SPOT_1_EXPECTED_RESULT_FILES,
  SPOT_1_FILENAME,
  SPOT_1_FILESIZE,
@@ -367,7 +373,10 @@ def test_cli_run_submit_and_describe_and_cancel_and_download_and_delete( # noqa
  record_property("tested-item-id", "TC-APPLICATION-CLI-02")
  csv_content = "external_id;checksum_base64_crc32c;resolution_mpp;width_px;height_px;staining_method;tissue;disease;"
  csv_content += "platform_bucket_url\n"
- csv_content += ";5onqtA==;0.26268186053789266;7447;7196;H&E;LUNG;LUNG_CANCER;gs://bucket/test"
+ csv_content += (
+ f"{SPOT_0_FILENAME};{SPOT_0_CRC32C};{SPOT_0_RESOLUTION_MPP};{SPOT_0_WIDTH};{SPOT_0_HEIGHT}"
+ f";H&E;LUNG;LUNG_CANCER;{SPOT_0_GS_URL}"
+ )
  csv_path = tmp_path / "dummy.csv"
  csv_path.write_text(csv_content)
  result = runner.invoke(

tests/aignostics/platform/resources/runs_test.py

@@ -16,11 +16,7 @@
  RunReadResponse,
 )
 
-from aignostics.platform.resources.runs import (
- LIST_APPLICATION_RUNS_MAX_PAGE_SIZE,
- Run,
- Runs,
-)
+from aignostics.platform.resources.runs import LIST_APPLICATION_RUNS_MAX_PAGE_SIZE, Run, Runs
 from aignostics.platform.resources.utils import PAGE_SIZE
 
 
@@ -577,6 +573,64 @@ def test_runs_list_delegates_to_list_data(runs, mock_api) -> None:
  assert "nocache" not in call_kwargs
 
 
+@pytest.mark.unit
+def test_application_run_results_with_filters(app_run, mock_api) -> None:
+ """Test that Run.results() correctly maps item_ids and external_ids to API parameters.
+
+ Verifies that:
+ - item_ids maps to item_id__in
+ - external_ids maps to external_id__in
+ """
+ # Arrange
+ item_ids = ["item-1", "item-2"]
+ external_ids = ["ext-1", "ext-2"]
+ page1 = [Mock(spec=ItemResultReadResponse) for _ in range(PAGE_SIZE)]
+ page2 = [Mock(spec=ItemResultReadResponse) for _ in range(3)]
+ mock_api.list_run_items_v1_runs_run_id_items_get.side_effect = [page1, page2]
+
+ # Act
+ result = list(app_run.results(item_ids=item_ids, external_ids=external_ids))
+
+ # Assert - filters are passed and pagination still works
+ assert len(result) == PAGE_SIZE + 3
+ assert mock_api.list_run_items_v1_runs_run_id_items_get.call_count == 2
+ for call in mock_api.list_run_items_v1_runs_run_id_items_get.call_args_list:
+ call_kwargs = call[1]
+ assert call_kwargs["item_id__in"] == item_ids
+ assert call_kwargs["external_id__in"] == external_ids
+ assert call_kwargs["run_id"] == app_run.run_id
+
+
+@pytest.mark.unit
+def test_application_run_results_without_filters_omits_filter_kwargs(app_run, mock_api) -> None:
+ """Test that Run.results() does not pass filter kwargs when no filters are provided."""
+ # Arrange
+ mock_api.list_run_items_v1_runs_run_id_items_get.return_value = []
+
+ # Act
+ list(app_run.results())
+
+ # Assert
+ call_kwargs = mock_api.list_run_items_v1_runs_run_id_items_get.call_args[1]
+ assert "item_id__in" not in call_kwargs
+ assert "external_id__in" not in call_kwargs
+
+
+@pytest.mark.unit
+def test_application_run_results_with_empty_list_filters_omits_filter_kwargs(app_run, mock_api) -> None:
+ """Test that Run.results() treats empty lists same as None (no filter applied)."""
+ # Arrange
+ mock_api.list_run_items_v1_runs_run_id_items_get.return_value = []
+
+ # Act - empty lists should behave like None
+ list(app_run.results(item_ids=[], external_ids=[]))
+
+ # Assert - filter kwargs should NOT be present
+ call_kwargs = mock_api.list_run_items_v1_runs_run_id_items_get.call_args[1]
+ assert "item_id__in" not in call_kwargs
+ assert "external_id__in" not in call_kwargs
+
+
 @pytest.mark.unit
 @pytest.mark.parametrize(
  ("hide_platform_queue_position", "expected_platform_queue_position"),