chore(llmobs): restore and deprecate managed prompt label (#19399)

## Description

- Restored `ManagedPrompt.label` removed in #19047
- Direct access emits debtcollector warning
- Internal reads do not warn

## Testing

<!-- Describe your testing strategy or note what tests are included -->

## Risks

<!-- Note any risks associated with this change, or "None" if no risks -->

## Additional Notes

<!-- Any other information that would be helpful for reviewers -->


Co-authored-by: brettlangdon <brett.langdon@datadoghq.com>

Author: PROFeNoM

ddtrace/llmobs/_prompts/manager.py

@@ -451,7 +451,7 @@ def _fetch_http(self, req: _PromptRequest, timeout: float) -> tuple[Optional[Man
 
             if status == 200:
                 source: Literal["registry", "resolve"] = "resolve" if req.use_resolve else "registry"
-                prompt = self._parse_prompt(body, source=source)
+                prompt = self._parse_prompt(body, source=source, label=req.label)
                 return prompt, False, ""
 
             not_found = status == 404
@@ -484,6 +484,7 @@ def _build_path(self, prompt_id: str, label: Optional[str], version: Optional[in
     def _parse_prompt(
         raw: Union[str, dict[str, Any]],
         source: Literal["registry", "ff", "resolve"],
+        label: Optional[str] = None,
     ) -> Optional[ManagedPrompt]:
         try:
             if isinstance(raw, str):
@@ -504,6 +505,7 @@ def _parse_prompt(
             return ManagedPrompt(
                 id=prompt_id,
                 version=str(version),
+                label=data.get("label", label),
                 source=source,
                 template=extract_template(data, default=[]),
                 _uuid=data.get("prompt_uuid"),

ddtrace/llmobs/_prompts/prompt.py

@@ -5,13 +5,15 @@
 from typing import Optional
 from typing import Union
 
+from ddtrace.internal.utils.deprecations import DDTraceDeprecationWarning
 from ddtrace.llmobs._prompts.utils import extract_template
 from ddtrace.llmobs._prompts.utils import render_chat
 from ddtrace.llmobs._prompts.utils import safe_substitute
 from ddtrace.llmobs._utils import attach_prompt
 from ddtrace.llmobs.types import Message
 from ddtrace.llmobs.types import Prompt
 from ddtrace.llmobs.types import PromptFallback
+from ddtrace.vendor.debtcollector import deprecate
 
 
 @dataclass(frozen=True)
@@ -24,16 +26,25 @@ class ManagedPrompt:
         - to_annotation_dict(**vars) -> dict[str, Any]
 
     INTERNAL (may change):
-        - All fields (id, version, source, template)
+        - All fields (id, version, label, source, template)
     """
 
     id: str
     version: str
+    label: Optional[str]
     source: Literal["registry", "cache", "fallback", "ff", "resolve"]
     template: Union[str, list[Message]]
     _uuid: Optional[str] = None
     _version_uuid: Optional[str] = None
 
+    def __getattribute__(self, name: str) -> Any:
+        if name == "label":
+            deprecate(  # type: ignore[no-untyped-call]
+                prefix="The 'label' property of ManagedPrompt is deprecated",
+                category=DDTraceDeprecationWarning,
+            )
+        return object.__getattribute__(self, name)
+
     def format(self, **variables: str) -> Union[str, list[Message]]:
         """
         Render the template with variables.
@@ -73,6 +84,9 @@ def to_annotation_dict(self, **variables: Any) -> Prompt:
         }
         if variables:
             result["variables"] = variables
+        label = object.__getattribute__(self, "label")
+        if label:
+            result["label"] = label
         if self._uuid:
             result["prompt_uuid"] = self._uuid
         if self._version_uuid:
@@ -86,13 +100,15 @@ def to_annotation_dict(self, **variables: Any) -> Prompt:
         return result
 
     def __repr__(self) -> str:
-        return f"ManagedPrompt(id={self.id!r}, version={self.version!r}, source={self.source!r})"
+        label = object.__getattribute__(self, "label")
+        return f"ManagedPrompt(id={self.id!r}, version={self.version!r}, label={label!r}, source={self.source!r})"
 
     def _serialize(self) -> dict[str, Any]:
         """Serialize to a JSON-compatible dict for cache storage."""
         return {
             "id": self.id,
             "version": self.version,
+            "label": object.__getattribute__(self, "label"),
             "source": self.source,
             "template": self.template,
             "_uuid": self._uuid,
@@ -105,6 +121,7 @@ def _deserialize(cls, data: dict[str, Any]) -> "ManagedPrompt":
         return cls(
             id=data["id"],
             version=data["version"],
+            label=data["label"],
             source=data.get("source", "cache"),
             template=data["template"],
             _uuid=data.get("_uuid"),
@@ -115,7 +132,7 @@ def _with_source(self, source: Literal["registry", "cache", "fallback"]) -> "Man
         """Create a copy with a different source. Used internally for caching."""
         if self.source == source:
             return self
-        return replace(self, source=source)
+        return replace(self, source=source, label=object.__getattribute__(self, "label"))
 
     @classmethod
     def from_fallback(
@@ -130,7 +147,7 @@ def from_fallback(
             fallback: A string, message list, Prompt dict, or callable returning any of those.
 
         Returns:
-            A ManagedPrompt with source="fallback".
+            A ManagedPrompt with source="fallback" and label=None.
         """
         template: Union[str, list[Message]] = ""
         version = "fallback"
@@ -146,6 +163,7 @@ def from_fallback(
         return cls(
             id=prompt_id,
             version=version,
+            label=None,
             source="fallback",
             template=template,
         )

releasenotes/notes/llmobs-prompt-labels-ce04882fdbe05721.yaml

@@ -1,4 +1,4 @@
 ---
 deprecations:
   - |
-    LLM Observability: Managed prompts no longer expose deprecated deployment label metadata. #19047
+    LLM Observability: The ``ManagedPrompt.label`` property is deprecated. #19399

tests/llmobs/test_prompts.py

@@ -206,16 +206,29 @@ def test_label_parameter(self):
             with pytest.warns(DDTraceDeprecationWarning):
                 prod_prompt = LLMObs.get_prompt("greeting", label="production")
         assert prod_prompt.version == "v1"
-        assert all(not hasattr(prod_prompt, field) for field in ("label", "labels"))
+        with pytest.warns(DDTraceDeprecationWarning):
+            assert prod_prompt.label == "production"
 
         LLMObs.clear_prompt_cache(hot=True, warm=True)
 
         with mock_api(200, DEV_PROMPT_RESPONSE):
             with pytest.warns(DDTraceDeprecationWarning):
                 dev_prompt = LLMObs.get_prompt("greeting", label="development")
         assert dev_prompt.version == "dev-v1"
+        with pytest.warns(DDTraceDeprecationWarning):
+            assert dev_prompt.label == "development"
         assert "DEBUG" in dev_prompt.format(name="Test")
 
+    def test_internal_label_reads_do_not_warn(self):
+        prompt = ManagedPrompt(id="greeting", version="v1", label="production", source="registry", template="Hello!")
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DDTraceDeprecationWarning)
+            assert prompt.to_annotation_dict()["label"] == "production"
+            assert "label='production'" in repr(prompt)
+            assert prompt._serialize()["label"] == "production"
+            assert prompt._with_source("cache").source == "cache"
+
     def test_string_fallback_on_error(self):
         """String fallback used when API returns 500."""
         with mock_api(500, "Internal Server Error"):
@@ -498,7 +511,7 @@ def test_route_env_agent_to_ff(self):
 
     def test_route_env_agentless_to_http_resolve(self):
         manager = _make_manager(agentless=True)
-        sentinel = ManagedPrompt(id="greeting", version="v1", source="resolve", template="Hi")
+        sentinel = ManagedPrompt(id="greeting", version="v1", label="production", source="resolve", template="Hi")
         with patch.object(manager, "_fetch_from_ff") as ff_mock:
             with patch.object(manager, "_get_prompt_http", return_value=sentinel) as http_mock:
                 with patch("ddtrace.llmobs._prompts.manager.config") as cfg:
@@ -541,6 +554,7 @@ def test_route_targeting_key_to_ff(self):
         ff_prompt = ManagedPrompt(
             id="greeting",
             version="ff-v1",
+            label=None,
             source="ff",
             template="Hello!",
         )
@@ -564,7 +578,7 @@ def test_route_label_targeting_conflict_warns(self):
     # which resolves the same env-scoped variant server-side.
     def test_route_not_ready_to_http_resolve(self):
         manager = _make_manager()
-        sentinel = ManagedPrompt(id="greeting", version="v1", source="resolve", template="Hi")
+        sentinel = ManagedPrompt(id="greeting", version="v1", label=None, source="resolve", template="Hi")
         with _ffe_enabled():
             with patch.object(manager, "_get_prompt_http", return_value=sentinel) as http_mock:
                 prompt = manager.get_prompt("greeting")
@@ -575,7 +589,7 @@ def test_route_not_ready_to_http_resolve(self):
 
     def test_route_no_flag_to_http_resolve(self):
         manager = _make_manager()
-        sentinel = ManagedPrompt(id="greeting", version="v1", source="resolve", template="Hi")
+        sentinel = ManagedPrompt(id="greeting", version="v1", label=None, source="resolve", template="Hi")
         with _ffe_enabled():
             _deliver_prompt_flag("other-prompt", {"prompt_id": "other-prompt", "version": "1", "template": "x"})
             with patch.object(manager, "_get_prompt_http", return_value=sentinel) as http_mock:
@@ -762,7 +776,7 @@ def test_delete_prompt_evicts_cache(self):
         manager = _make_manager()
         manager._hot_cache.set(
             "my-prompt:production",
-            ManagedPrompt(id="my-prompt", version="v1", source="registry", template=[]),
+            ManagedPrompt(id="my-prompt", version="v1", label="production", source="registry", template=[]),
         )
         assert len(manager._hot_cache) == 1
 
@@ -860,11 +874,11 @@ def test_hot_evict_does_not_over_evict_colon_prefixed_ids(self):
         manager = _make_manager()
         manager._hot_cache.set(
             "foo:production",
-            ManagedPrompt(id="foo", version="v1", source="registry", template=[]),
+            ManagedPrompt(id="foo", version="v1", label="production", source="registry", template=[]),
         )
         manager._hot_cache.set(
             "foo:bar:production",
-            ManagedPrompt(id="foo:bar", version="v1", source="registry", template=[]),
+            ManagedPrompt(id="foo:bar", version="v1", label="production", source="registry", template=[]),
         )
         assert len(manager._hot_cache) == 2
 
@@ -876,8 +890,8 @@ def test_hot_evict_does_not_over_evict_colon_prefixed_ids(self):
     def test_warm_cache_distinct_ids_do_not_collide_on_path(self, tmp_path):
         """Regression: 'a/b' and 'a_b' must not share a cache file (lossy sanitization served wrong prompts)."""
         cache = WarmCache(cache_dir=str(tmp_path), ttl_seconds=60)
-        cache.set("a/b:", ManagedPrompt(id="a/b", version="v1", source="registry", template=[]))
-        cache.set("a_b:", ManagedPrompt(id="a_b", version="v2", source="registry", template=[]))
+        cache.set("a/b:", ManagedPrompt(id="a/b", version="v1", label=None, source="registry", template=[]))
+        cache.set("a_b:", ManagedPrompt(id="a_b", version="v2", label=None, source="registry", template=[]))
 
         assert cache.get("a/b:")[0].id == "a/b"
         assert cache.get("a_b:")[0].id == "a_b"
@@ -909,7 +923,7 @@ def test_hot_cache_lru_eviction():
     cache = HotCache(ttl_seconds=60, maxsize=2)
 
     def mk(v):
-        return ManagedPrompt(id=v, version="1", source="resolve", template="x")
+        return ManagedPrompt(id=v, version="1", label=None, source="resolve", template="x")
 
     cache.set("a", mk("a"))
     cache.set("b", mk("b"))