Client.get_autotag_refinement_metrics (#228)

* add new endpoint

* docs

* tests

Author: jihan-yin

nucleus/__init__.py

@@ -841,6 +841,26 @@ def delete_autotag(self, autotag_id: str) -> dict:
         """
         return self.make_request({}, f"autotag/{autotag_id}", requests.delete)
 
+    def get_autotag_refinement_metrics(self, autotag_id: str) -> dict:
+        """Retrieves refinement metrics for an autotag by ID.
+
+        Parameters:
+            autotag_id: Nucleus-generated autotag ID (starts with ``tag_``). This can
+              be retrieved via :meth:`list_autotags` or a Nucleus dashboard URL.
+
+        Returns:
+            Response payload::
+
+
+                {
+                    "total_refinement_steps": int
+                    "average_positives_selected_per_refinement": int
+                }
+        """
+        return self.make_request(
+            {}, f"autotag/{autotag_id}/refinementMetrics", requests.get
+        )
+
     def delete_model(self, model_id: str) -> dict:
         """Deletes a model by ID.
 

tests/test_autotag.py

@@ -93,3 +93,12 @@ def test_export_slice_embeddings(CLIENT):
         embeddings = test_slice.export_embeddings()
         assert "embedding_vector" in embeddings[0]
         assert "reference_id" in embeddings[0]
+
+
+def test_get_autotag_refinement_metrics(CLIENT):
+    if running_as_nucleus_pytest_user(CLIENT):
+        response = CLIENT.get_autotag_refinement_metrics(
+            "tag_c5jwvzzde8c00604mkx0"
+        )
+        assert response["total_refinement_steps"] >= 0
+        assert response["average_positives_selected_per_refinement"] >= 0