Add eval results and test run info support to trace update endpoints

Add two new trace update methods accessible via client.traces:

- traces.update(): PATCH /traces/id/{trace_id} to update a trace by ID
- traces.update_by_otel_span_id(): PATCH /traces/otel-span-id/{otel_span_id_hex}
  to update a trace by OpenTelemetry span ID

Both endpoints accept optional fields (only sent when provided):
- custom_metadata: Dict of key-value metadata pairs
- feedback: Dict of feedback values
- eval_results: Dict of evaluation scores (bool or float)
- test_run_info: TestRunInfo with test_run_id and test_case_id

Resolves ENG-5053

Co-authored-by: Nico Tonozzi <nico@nicot.us>

Author: cursoragent

src/freeplay/__init__.py

@@ -3,6 +3,7 @@
 from .model import TestRunInfo
 from .resources.recordings import CallInfo, ResponseInfo, RecordPayload, UsageTokens
 from .resources.sessions import SessionInfo, TraceInfo
+from .resources.traces import TraceUpdateResponse
 from .support import CustomMetadata
 
 __all__ = [
@@ -15,5 +16,6 @@
     "SessionInfo",
     "TestRunInfo",
     "TraceInfo",
+    "TraceUpdateResponse",
     "UsageTokens",
 ]

src/freeplay/freeplay.py

@@ -8,6 +8,7 @@
 from freeplay.resources.sessions import Sessions
 from freeplay.resources.test_cases import TestCases
 from freeplay.resources.test_runs import TestRuns
+from freeplay.resources.traces import Traces
 from freeplay.support import CallSupport
 
 
@@ -41,3 +42,4 @@ def __init__(
         self.sessions = Sessions(self.call_support)
         self.test_runs = TestRuns(self.call_support)
         self.test_cases = TestCases(self.call_support)
+        self.traces = Traces(self.call_support)

src/freeplay/resources/traces.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+from typing import Dict, Optional, Union
+
+from freeplay.model import FeedbackValue, TestRunInfo
+from freeplay.support import CallSupport, CustomMetadata
+
+
+@dataclass
+class TraceUpdateResponse:
+    pass
+
+
+class Traces:
+    def __init__(self, call_support: CallSupport) -> None:
+        self.call_support = call_support
+
+    def update(
+        self,
+        project_id: str,
+        session_id: str,
+        trace_id: str,
+        custom_metadata: CustomMetadata = None,
+        feedback: Optional[Dict[str, FeedbackValue]] = None,
+        eval_results: Optional[Dict[str, Union[bool, float]]] = None,
+        test_run_info: Optional[TestRunInfo] = None,
+    ) -> TraceUpdateResponse:
+        self.call_support.update_trace(
+            project_id,
+            session_id,
+            trace_id,
+            custom_metadata=custom_metadata,
+            feedback=feedback,
+            eval_results=eval_results,
+            test_run_info=test_run_info,
+        )
+        return TraceUpdateResponse()
+
+    def update_by_otel_span_id(
+        self,
+        project_id: str,
+        session_id: str,
+        otel_span_id_hex: str,
+        custom_metadata: CustomMetadata = None,
+        feedback: Optional[Dict[str, FeedbackValue]] = None,
+        eval_results: Optional[Dict[str, Union[bool, float]]] = None,
+        test_run_info: Optional[TestRunInfo] = None,
+    ) -> TraceUpdateResponse:
+        self.call_support.update_trace_by_otel_span_id(
+            project_id,
+            session_id,
+            otel_span_id_hex,
+            custom_metadata=custom_metadata,
+            feedback=feedback,
+            eval_results=eval_results,
+            test_run_info=test_run_info,
+        )
+        return TraceUpdateResponse()

src/freeplay/support.py

@@ -500,6 +500,78 @@ def update_trace_metadata(
                 response,
             )
 
+    def _build_trace_update_payload(
+        self,
+        custom_metadata: CustomMetadata = None,
+        feedback: Optional[Dict[str, FeedbackValue]] = None,
+        eval_results: Optional[Dict[str, Union[bool, float]]] = None,
+        test_run_info: Optional[TestRunInfo] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {}
+        if custom_metadata is not None:
+            payload["custom_metadata"] = custom_metadata
+        if feedback is not None:
+            payload["feedback"] = feedback
+        if eval_results is not None:
+            payload["eval_results"] = eval_results
+        if test_run_info is not None:
+            payload["test_run_info"] = asdict(test_run_info)
+        return payload
+
+    def update_trace(
+        self,
+        project_id: str,
+        session_id: str,
+        trace_id: str,
+        custom_metadata: CustomMetadata = None,
+        feedback: Optional[Dict[str, FeedbackValue]] = None,
+        eval_results: Optional[Dict[str, Union[bool, float]]] = None,
+        test_run_info: Optional[TestRunInfo] = None,
+    ) -> None:
+        payload = self._build_trace_update_payload(
+            custom_metadata=custom_metadata,
+            feedback=feedback,
+            eval_results=eval_results,
+            test_run_info=test_run_info,
+        )
+        response = api_support.patch_raw(
+            self.freeplay_api_key,
+            f"{self.api_base}/v2/projects/{project_id}/sessions/{session_id}/traces/id/{trace_id}",
+            payload,
+        )
+        if response.status_code != 200:
+            raise freeplay_response_error(
+                f"Error updating trace {trace_id} in project {project_id}",
+                response,
+            )
+
+    def update_trace_by_otel_span_id(
+        self,
+        project_id: str,
+        session_id: str,
+        otel_span_id_hex: str,
+        custom_metadata: CustomMetadata = None,
+        feedback: Optional[Dict[str, FeedbackValue]] = None,
+        eval_results: Optional[Dict[str, Union[bool, float]]] = None,
+        test_run_info: Optional[TestRunInfo] = None,
+    ) -> None:
+        payload = self._build_trace_update_payload(
+            custom_metadata=custom_metadata,
+            feedback=feedback,
+            eval_results=eval_results,
+            test_run_info=test_run_info,
+        )
+        response = api_support.patch_raw(
+            self.freeplay_api_key,
+            f"{self.api_base}/v2/projects/{project_id}/sessions/{session_id}/traces/otel-span-id/{otel_span_id_hex}",
+            payload,
+        )
+        if response.status_code != 200:
+            raise freeplay_response_error(
+                f"Error updating trace with otel span id {otel_span_id_hex} in project {project_id}",
+                response,
+            )
+
     def create_test_run(
         self,
         project_id: str,