chore: support dataset versioning via SDK

Author: marliessophie

langfuse/_client/client.py

@@ -2442,13 +2442,20 @@ def get_trace_url(self, *, trace_id: Optional[str] = None) -> Optional[str]:
         )
 
     def get_dataset(
-        self, name: str, *, fetch_items_page_size: Optional[int] = 50
+        self,
+        name: str,
+        *,
+        fetch_items_page_size: Optional[int] = 50,
+        version: Optional[datetime] = None,
     ) -> "DatasetClient":
         """Fetch a dataset by its name.
 
         Args:
             name (str): The name of the dataset to fetch.
             fetch_items_page_size (Optional[int]): All items of the dataset will be fetched in chunks of this size. Defaults to 50.
+            version (Optional[datetime]): Retrieve dataset items as they existed at this specific point in time (UTC).
+                If provided, returns the state of items at the specified UTC timestamp.
+                If not provided, returns the latest version. Must be a timezone-aware datetime object in UTC.
 
         Returns:
             DatasetClient: The dataset with the given name.
@@ -2465,6 +2472,7 @@ def get_dataset(
                     dataset_name=self._url_encode(name, is_url_param=True),
                     page=page,
                     limit=fetch_items_page_size,
+                    version=version,
                 )
                 dataset_items.extend(new_items.data)
 

tests/test_datasets.py

@@ -527,3 +527,41 @@ def test_delete_dataset_run_with_folder_names():
     # Verify the run is deleted
     runs_after = langfuse.get_dataset_runs(dataset_name=folder_name)
     assert len(runs_after.data) == 0
+
+
+def test_get_dataset_with_version():
+    """Test that get_dataset correctly filters items by version timestamp."""
+    from datetime import datetime, timezone
+    import time
+
+    langfuse = Langfuse(debug=False)
+
+    # Create dataset
+    name = create_uuid()
+    langfuse.create_dataset(name=name)
+
+    # Create first item
+    item1 = langfuse.create_dataset_item(dataset_name=name, input={"version": "v1"})
+    langfuse.flush()
+    time.sleep(3)  # Ensure persistence and clear temporal separation
+
+    # Capture timestamp AFTER first item, BEFORE second item
+    query_timestamp = datetime.now(timezone.utc)
+    time.sleep(3)  # Ensure second item is created AFTER query_timestamp
+
+    # Create second item
+    langfuse.create_dataset_item(dataset_name=name, input={"version": "v2"})
+    langfuse.flush()
+    time.sleep(3)  # Ensure persistence
+
+    # Fetch at the query_timestamp (should only return first item)
+    dataset = langfuse.get_dataset(name, version=query_timestamp)
+
+    # Verify only first item is retrieved
+    assert len(dataset.items) == 1
+    assert dataset.items[0].input == {"version": "v1"}
+    assert dataset.items[0].id == item1.id
+
+    # Verify fetching without version returns both items (latest)
+    dataset_latest = langfuse.get_dataset(name)
+    assert len(dataset_latest.items) == 2