chore: deprecate select child_run_ids in list_runs (#2066)

Soft deprecate `child_run_ids` value in `select` for:
- TS: `listRuns`
- Python: `Client.list_runs`, `AsyncClient.list_runs`

This column will not be ported next major version of the API.

Author: QuentinBrosse

js/src/client.ts

@@ -227,6 +227,9 @@ interface ListRunsParams {
   treeFilter?: string;
   /**
    * The values to include in the response.
+   *
+   * Note: The 'child_run_ids' value is deprecated and will be removed in a future version.
+   * This field is no longer populated by the API.
    */
   select?: string[];
 }
@@ -2141,6 +2144,12 @@ export class Client implements LangSmithTracingClientInterface {
       order,
     };
 
+    if (body.select.includes("child_run_ids")) {
+      warnOnce(
+        "Deprecated: 'child_run_ids' in the listRuns select parameter is deprecated and will be removed in a future version."
+      );
+    }
+
     let runsYielded = 0;
     for await (const runs of this._getCursorPaginatedList<Run>(
       "/runs/query",

js/src/tests/client.test.ts

@@ -685,4 +685,52 @@ describe("Client", () => {
       });
     });
   });
+
+  describe("listRuns", () => {
+    it("should warn when child_run_ids is in select parameter", async () => {
+      const consoleWarnSpy = jest
+        .spyOn(console, "warn")
+        .mockImplementation(() => {});
+
+      // Create mock fetch function
+      const mockFetch = jest.fn().mockImplementation(async () => ({
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        json: async () => ({ runs: [] }),
+      }));
+
+      const client = new Client({
+        apiKey: "org-scoped-key",
+        fetchImplementation: mockFetch as any,
+      });
+
+      // Test that warning is issued when child_run_ids is in select
+      const runs = [];
+      for await (const run of client.listRuns({
+        projectId: "00000000-0000-0000-0000-000000000000",
+        select: ["id", "name", "child_run_ids"],
+      })) {
+        runs.push(run);
+      }
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        expect.stringMatching(
+          "Deprecated: 'child_run_ids' in the listRuns select parameter is deprecated and will be removed in a future version."
+        )
+      );
+      consoleWarnSpy.mockClear();
+
+      // Test that no warning is issued when child_run_ids is not in select
+      for await (const run of client.listRuns({
+        projectId: "00000000-0000-0000-0000-000000000000",
+        select: ["id", "name"],
+      })) {
+        runs.push(run);
+      }
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+      consoleWarnSpy.mockRestore();
+    });
+  });
 });

python/langsmith/async_client.py

@@ -7,6 +7,7 @@
 import datetime
 import json
 import uuid
+import warnings
 from collections.abc import AsyncGenerator, AsyncIterator, Mapping, Sequence
 from typing import (
     Any,
@@ -412,6 +413,12 @@ async def list_runs(
             )
             project_ids.extend([project.id for project in projects])
 
+        if select and "child_run_ids" in select:
+            warnings.warn(
+                "The child_run_ids field is deprecated and will be removed in following versions",
+                DeprecationWarning,
+            )
+
         body_query: dict[str, Any] = {
             "session": project_ids if project_ids else None,
             "run_type": run_type,

python/langsmith/client.py

@@ -2887,7 +2887,15 @@ def list_runs(
             "total_tokens",
             "trace_id",
         ]
+
         select = select or default_select
+
+        if "child_run_ids" in select:
+            warnings.warn(
+                "The child_run_ids field is deprecated and will be removed in following versions",
+                DeprecationWarning,
+            )
+
         body_query: dict[str, Any] = {
             "session": project_ids if project_ids else None,
             "run_type": run_type,

python/langsmith/schemas.py

@@ -424,7 +424,7 @@ class Run(RunBase):
     session_id: Optional[UUID] = None
     """The project ID this run belongs to."""
     child_run_ids: Optional[list[UUID]] = None
-    """The child run IDs of this run."""
+    """Deprecated: The child run IDs of this run."""
     child_runs: Optional[list[Run]] = None
     """The child runs of this run, if instructed to load using the client
     These are not populated by default, as it is a heavier query to make."""

python/tests/unit_tests/test_async_client.py

@@ -0,0 +1,41 @@
+"""Test the AsyncClient."""
+
+import warnings
+from unittest import mock
+from uuid import uuid4
+
+import pytest
+
+from langsmith import AsyncClient
+
+
+@mock.patch("langsmith.async_client.httpx.AsyncClient")
+@pytest.mark.asyncio
+async def test_list_runs_child_run_ids_deprecation_warning(
+    mock_client_cls: mock.Mock,
+) -> None:
+    mock_httpx_client = mock.AsyncMock()
+    mock_client_cls.return_value = mock_httpx_client
+
+    # Mock the response for list_runs
+    mock_response = mock.Mock()
+    mock_response.json.return_value = {"runs": []}
+    mock_response.status_code = 200
+    mock_response.raise_for_status = mock.Mock()
+    mock_httpx_client.request.return_value = mock_response
+
+    client = AsyncClient()
+
+    # Test that deprecation warning is raised when child_run_ids is in select
+    with pytest.warns(DeprecationWarning, match="child_run_ids field is deprecated"):
+        async for _ in client.list_runs(
+            project_id=uuid4(),
+            select=["id", "name", "child_run_ids"],
+        ):
+            pass
+
+    # Test that no warning is raised when child_run_ids is not in select
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+        async for _ in client.list_runs(project_id=uuid4(), select=["id", "name"]):
+            pass

python/tests/unit_tests/test_client.py

@@ -4326,3 +4326,30 @@ def track_processing(runs):
                 file_obj.close()
             except Exception:
                 pass
+
+
+@mock.patch("langsmith.client.requests.Session")
+def test_list_runs_child_run_ids_deprecation_warning(
+    mock_session_cls: mock.Mock,
+) -> None:
+    """Test that using child_run_ids in select parameter raises a deprecation warning."""
+
+    mock_session = mock.Mock()
+    mock_session_cls.return_value = mock_session
+    mock_session.request.return_value.json.return_value = {"runs": []}
+
+    client = Client()
+
+    # Test that deprecation warning is raised when child_run_ids is in select
+    with pytest.warns(DeprecationWarning, match="child_run_ids field is deprecated"):
+        list(
+            client.list_runs(
+                project_id=uuid.uuid4(),
+                select=["id", "name", "child_run_ids"],
+            )
+        )
+
+    # Test that no warning is raised when child_run_ids is not in select
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+        list(client.list_runs(project_id=uuid.uuid4(), select=["id", "name"]))