task(logger): update types / param docs for log_feedback and experiments

Author: barrettpyke

py/src/braintrust/logger.py

@@ -3391,7 +3391,7 @@ def _log_feedback_impl(
     expected: Any | None = None,
     tags: Sequence[str] | None = None,
     comment: str | None = None,
-    metadata: Metadata | None = None,
+    metadata: object | None = None,
     source: Literal["external", "app", "api", None] = None,
 ):
     if source is None:
@@ -3880,7 +3880,7 @@ def log_feedback(
         expected: Any | None = None,
         tags: Sequence[str] | None = None,
         comment: str | None = None,
-        metadata: Metadata | None = None,
+        metadata: object | None = None,
         source: Literal["external", "app", "api", None] = None,
     ) -> None:
         """
@@ -3891,7 +3891,7 @@ def log_feedback(
         :param expected: (Optional) the ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not.
         :param tags: (Optional) a list of strings that you can use to filter and group records later.
         :param comment: (Optional) an optional comment string to log about the event.
-        :param metadata: (Optional) a dictionary with additional data about the feedback. If you have a `user_id`, you can log it here and access it in the Braintrust UI. Note, this metadata does not correspond to the main event itself, but rather the audit log attached to the event.
+        :param metadata: (Optional) a dictionary, or an object that serializes to a dictionary, with additional data about the feedback. If you have a `user_id`, you can log it here and access it in the Braintrust UI. Note, this metadata does not correspond to the main event itself, but rather the audit log attached to the event. The values in `metadata` can be any JSON-serializable type, but its keys must be strings.
         :param source: (Optional) the source of the feedback. Must be one of "external" (default), "app", or "api".
         """
         return _log_feedback_impl(
@@ -5312,7 +5312,7 @@ def log_feedback(
         expected: Any | None = None,
         tags: Sequence[str] | None = None,
         comment: str | None = None,
-        metadata: Metadata | None = None,
+        metadata: object | None = None,
         source: Literal["external", "app", "api", None] = None,
     ) -> None:
         """
@@ -5323,7 +5323,7 @@ def log_feedback(
         :param expected: (Optional) the ground truth value (an arbitrary, JSON serializable object) that you'd compare to `output` to determine if your `output` value is correct or not.
         :param tags: (Optional) a list of strings that you can use to filter and group records later.
         :param comment: (Optional) an optional comment string to log about the event.
-        :param metadata: (Optional) a dictionary with additional data about the feedback. If you have a `user_id`, you can log it here and access it in the Braintrust UI. Note, this metadata does not correspond to the main event itself, but rather the audit log attached to the event.
+        :param metadata: (Optional) a dictionary, or an object that serializes to a dictionary, with additional data about the feedback. If you have a `user_id`, you can log it here and access it in the Braintrust UI. Note, this metadata does not correspond to the main event itself, but rather the audit log attached to the event. The values in `metadata` can be any JSON-serializable type, but its keys must be strings.
         :param source: (Optional) the source of the feedback. Must be one of "external" (default), "app", or "api".
         """
         return _log_feedback_impl(

py/src/braintrust/test_logger.py

@@ -22,6 +22,7 @@
     init_logger,
     logger,
 )
+from braintrust.db_fields import AUDIT_METADATA_FIELD
 from braintrust.id_gen import OTELIDGenerator, get_id_generator
 from braintrust.logger import (
     RemoteEvalParameters,
@@ -858,22 +859,66 @@ class MetadataModel(BaseModel):
     assert logs[0]["metadata"] == {"foo": "bar"}
 
 
-def test_span_log_accepts_model_dump_metadata(with_memory_logger):
-    class MetadataModel:
-        def model_dump(self, **kwargs):
-            assert kwargs == {"exclude_none": True}
-            return {"foo": "bar"}
+class _ModelDumpMetadata:
+    def __init__(self, **values):
+        self.values = values
+
+    def model_dump(self, **kwargs):
+        assert kwargs == {"exclude_none": True}
+        return dict(self.values)
+
 
+def test_span_log_accepts_model_dump_metadata(with_memory_logger):
     logger = init_test_logger(__name__)
 
     with logger.start_span(name="test_span") as span:
-        span.log(metadata=MetadataModel())
+        span.log(metadata=_ModelDumpMetadata(foo="bar"))
+
+    logs = with_memory_logger.pop()
+    assert len(logs) == 1
+    assert logs[0]["metadata"] == {"foo": "bar"}
+
+
+def test_logger_log_accepts_model_dump_metadata(with_memory_logger):
+    logger = init_test_logger(__name__)
+
+    logger.log(input="input", output="output", metadata=_ModelDumpMetadata(foo="bar"))
+
+    logs = with_memory_logger.pop()
+    assert len(logs) == 1
+    assert logs[0]["metadata"] == {"foo": "bar"}
+
+
+def test_experiment_log_accepts_model_dump_metadata(with_memory_logger):
+    experiment = init_test_exp("test-experiment", "test-project")
+
+    experiment.log(input="input", output="output", scores={"score": 1}, metadata=_ModelDumpMetadata(foo="bar"))
 
     logs = with_memory_logger.pop()
     assert len(logs) == 1
     assert logs[0]["metadata"] == {"foo": "bar"}
 
 
+def test_logger_log_feedback_accepts_model_dump_metadata(with_memory_logger):
+    logger = init_test_logger(__name__)
+
+    logger.log_feedback(id="event-id", scores={"score": 1}, metadata=_ModelDumpMetadata(user_id="user-1"))
+
+    logs = with_memory_logger.pop()
+    assert len(logs) == 1
+    assert logs[0][AUDIT_METADATA_FIELD] == {"user_id": "user-1"}
+
+
+def test_experiment_log_feedback_accepts_model_dump_metadata(with_memory_logger):
+    experiment = init_test_exp("test-experiment", "test-project")
+
+    experiment.log_feedback(id="event-id", scores={"score": 1}, metadata=_ModelDumpMetadata(user_id="user-1"))
+
+    logs = with_memory_logger.pop()
+    assert len(logs) == 1
+    assert logs[0][AUDIT_METADATA_FIELD] == {"user_id": "user-1"}
+
+
 def test_span_log_rejects_metadata_with_non_string_keys(with_memory_logger):
     logger = init_test_logger(__name__)
 
@@ -2976,12 +3021,13 @@ def test_update_span_includes_span_id_and_root_span_id_from_export(with_memory_l
 
     with_memory_logger.pop()
 
-    braintrust.update_span(exported=exported, output="updated output")
+    braintrust.update_span(exported=exported, output="updated output", metadata=_ModelDumpMetadata(foo="bar"))
 
     logs = with_memory_logger.pop()
     updated_log = next(log for log in logs if log.get("output") == "updated output")
     assert updated_log["span_id"] == span_id
     assert updated_log["root_span_id"] == root_span_id
+    assert updated_log["metadata"] == {"foo": "bar"}
 
 
 def test_get_exporter_returns_v3_by_default():