update comments, examples

ddtrace/llmobs/_llmobs.py

@@ -808,11 +808,12 @@ def submit_evaluation_for(
                       Must be a string (categorical), integer (score), or float (score).
         :param dict span: A dictionary of shape {'span_id': str, 'trace_id': str} uniquely identifying
                             the span associated with this evaluation.
-        :param tuple span_with_tag_value: A dictionary of shape {'tag_key': str, 'tag_value': str} uniquely identifying
-                            the span associated with this evaluation.
+        :param dict span_with_tag_value: A dictionary with the format {'tag_key': str, 'tag_value': str}
+                            uniquely identifying the span associated with this evaluation.
         :param tags: A dictionary of string key-value pairs to tag the evaluation metric with.
         :param str ml_app: The name of the ML application
-        :param int timestamp_ms: The timestamp in milliseconds when the evaluation metric result was generated.
+        :param int timestamp_ms: The unix timestamp in milliseconds when the evaluation metric result was generated.
+                                    If not set, the current time will be used.
         """
         if cls.enabled is False:
             log.debug(
@@ -873,9 +874,8 @@ def submit_evaluation_for(
 
         if tags is not None and not isinstance(tags, dict):
             log.warning("tags must be a dictionary of string key-value pairs.")
-            tags = None
+            tags = {}
 
-        # initialize tags with default values that will be overridden by user-provided tags
         evaluation_tags = {
             "ddtrace.version": ddtrace.__version__,
             "ml_app": ml_app,
@@ -899,7 +899,7 @@ def submit_evaluation_for(
         evaluation_metric = {
             "join_on": join_on,
             "label": str(label),
-            "metric_type": metric_type.lower(),
+            "metric_type": metric_type,
             "timestamp_ms": timestamp_ms,
             "{}_value".format(metric_type): value,
             "ml_app": ml_app,

releasenotes/notes/submit-evaluation-for-01096d803d969e3e.yaml

@@ -1,16 +1,17 @@
 ---
 features:
   - |
-    LLM Observability: This introduces the ability to submit custom evaluations joined to a span by a tag key-value pair using the
-                      `LLMObs.submit_evaluation_for()` method. The tag key-value pair is expected to uniquely a span.
-                      Example usage: 
-                        - Evaluation joined by tag: `LLMObs.submit_evaluation_for(span_with_tag_value=("message_id", "dummy-message-id"), label="rating", ...)`.
+    LLM Observability: This introduces the `LLMObs.submit_evaluation_for` method, which provides the ability to join a custom evaluation 
+                        to a span using a tag key-value pair on the span. The tag key-value pair is expected to uniquely identify a single span. 
+                        Tag-based joining is an alternative to the existing method of joining evaluations to spans using trace and span IDs.
+                      Example usage:
+                        - Evaluation joined by tag: `LLMObs.submit_evaluation_for(span_with_tag_value={"tag_key": "message_id", "tag_value": "dummy_message_id"}, label="rating", ...)`.
                         - Evaluation joined by trace/span ID: `LLMObs.submit_evaluation_for(span={"trace_id": "...", "span_id": "..."}, label="rating", ...)`.
 deprecations:
   - |
-    LLM Observability: `LLMObs.submit_evaluation` is deprecated and will be removed in 3.0.0.
+    LLM Observability: `LLMObs.submit_evaluation` is deprecated and will be removed in ddtrace 3.0.0.
                         As an alternative to `LLMObs.submit_evaluation`, you can use `LLMObs.submit_evaluation_for` instead.
                         To migrate, replace `LLMObs.submit_evaluation(span_context={"span_id": ..., "trace_id": ...}, ...)` with:
                           `LLMObs.submit_evaluation_for(span={"span_id": ..., "trace_id": ...}, ...)
                         You may also join an evaluation to a span using a tag key-value pair like so:
-                          `LLMObs.submit_evaluation_for(span_with_tag_value=("tag_key", "tag_val"), ...)`
+                          `LLMObs.submit_evaluation_for(span_with_tag_value={"tag_key": ..., "tag_val": ...}, ...)`.