Tag LangSmith traces by deployment environment

.env.example

@@ -22,6 +22,9 @@ OPENROUTER_API_KEY=...
 LANGSMITH_API_KEY=...
 LANGSMITH_TRACING=true
 LANGSMITH_PROJECT=ai-tutor-app
+# Trace origin label (set HF Space variables to hf-dev or hf-prod; defaults to
+# huggingface-space when SPACE_HOST exists, otherwise local)
+# AI_TUTOR_DEPLOYMENT_ENV=local
 
 # To update documentation/add new course
 HF_TOKEN=... https://huggingface.co/settings/tokens to read or write to private DATASET repos e.g. https://huggingface.co/datasets/towardsai-tutors/ai-tutor-data/tree/main

app/agent_tracing.py

@@ -3,6 +3,9 @@ from __future__ import annotations
 import os
 
 DEFAULT_LANGSMITH_PROJECT = "ai-tutor-app"
+DEFAULT_LOCAL_DEPLOYMENT_ENVIRONMENT = "local"
+DEFAULT_HF_DEPLOYMENT_ENVIRONMENT = "huggingface-space"
+LOCAL_DEPLOYMENT_HOST = "local"
 
 TRUE_VALUES = {"1", "true", "t", "yes", "y", "on"}
 FALSE_VALUES = {"0", "false", "f", "no", "n", "off"}
@@ -27,6 +30,19 @@ def langsmith_tracing_enabled() -> bool:
     return bool(os.getenv("LANGSMITH_API_KEY"))
 
 
+def langsmith_deployment_identity() -> tuple[str, str]:
+    """Return stable environment and host labels for LangSmith traces."""
+    space_host = os.getenv("SPACE_HOST", "").strip()
+    environment = os.getenv("AI_TUTOR_DEPLOYMENT_ENV", "").strip()
+    if not environment:
+        environment = (
+            DEFAULT_HF_DEPLOYMENT_ENVIRONMENT
+            if space_host
+            else DEFAULT_LOCAL_DEPLOYMENT_ENVIRONMENT
+        )
+    return environment, space_host or LOCAL_DEPLOYMENT_HOST
+
+
 def configure_langsmith_environment() -> None:
     """Apply app defaults for LangSmith without requiring code changes in deploys."""
     if os.getenv("LANGSMITH_API_KEY") and os.getenv("LANGSMITH_TRACING") is None:

app/chat_service.py

@@ -40,6 +40,7 @@ from langgraph.graph.message import REMOVE_ALL_MESSAGES
 from langgraph.store.memory import InMemoryStore
 from langgraph.types import Command
 
+from .agent_tracing import langsmith_deployment_identity
 from .chat_types import ChatEvent, ChatRequest, ChatTurn, SourceMatch
 from .deepseek_chat import TutorChatDeepSeek
 from .memory_presets import (
@@ -2651,6 +2652,7 @@ def agent_run_config(
     memory_preset: str = "",
 ) -> dict[str, Any]:
     provider, actual_model = model_provider_and_name(request.model_name)
+    deployment_environment, deployment_host = langsmith_deployment_identity()
     tools = effective_tool_names(
         request.model_name,
         request.enabled_tools,
@@ -2672,10 +2674,14 @@ def agent_run_config(
                 f"provider:{provider}",
                 f"model:{actual_model}",
                 f"memory:{preset}",
+                f"environment:{deployment_environment}",
+                f"deployment:{deployment_host}",
                 *(f"tool:{tool_name}" for tool_name in tools),
             ],
             "metadata": {
                 "app": "ai-tutor-app",
+                "environment": deployment_environment,
+                "deployment_host": deployment_host,
                 "thread_id": active_thread_id,
                 "conversation_id": active_thread_id,
                 "message_id": message_id,

tests/test_agent_tracing.py

@@ -7,6 +7,7 @@ from unittest.mock import patch
 from app.agent_tracing import (
     DEFAULT_LANGSMITH_PROJECT,
     configure_langsmith_environment,
+    langsmith_deployment_identity,
     langsmith_tracing_enabled,
     parse_env_bool,
 )
@@ -40,6 +41,38 @@ class AgentTracingTestCase(unittest.TestCase):
             self.assertFalse(langsmith_tracing_enabled())
             self.assertNotIn("LANGSMITH_PROJECT", os.environ)
 
+    def test_deployment_identity_defaults_to_local(self) -> None:
+        with patch.dict(os.environ, {}, clear=True):
+            self.assertEqual(langsmith_deployment_identity(), ("local", "local"))
+
+    def test_deployment_identity_detects_hugging_face_space(self) -> None:
+        with patch.dict(
+            os.environ,
+            {"SPACE_HOST": "towardsai-tutors-ai-tutor-chatbot.hf.space"},
+            clear=True,
+        ):
+            self.assertEqual(
+                langsmith_deployment_identity(),
+                (
+                    "huggingface-space",
+                    "towardsai-tutors-ai-tutor-chatbot.hf.space",
+                ),
+            )
+
+    def test_explicit_deployment_environment_wins(self) -> None:
+        with patch.dict(
+            os.environ,
+            {
+                "AI_TUTOR_DEPLOYMENT_ENV": "hf-prod",
+                "SPACE_HOST": "towardsai-tutors-ai-tutor-chatbot.hf.space",
+            },
+            clear=True,
+        ):
+            self.assertEqual(
+                langsmith_deployment_identity(),
+                ("hf-prod", "towardsai-tutors-ai-tutor-chatbot.hf.space"),
+            )
+
     def test_project_is_preserved(self) -> None:
         with patch.dict(
             os.environ,

tests/test_chat_service.py

@@ -413,17 +413,34 @@ class ChatServiceTestCase(unittest.TestCase):
             enabled_tools=("web_search",),
         )
 
-        config = agent_run_config(request, "thread_123", "message_456")
+        with patch.dict(
+            os.environ,
+            {
+                "AI_TUTOR_DEPLOYMENT_ENV": "hf-prod",
+                "SPACE_HOST": "towardsai-tutors-ai-tutor-chatbot.hf.space",
+            },
+        ):
+            config = agent_run_config(request, "thread_123", "message_456")
 
         self.assertEqual(config["configurable"], {"thread_id": "thread_123"})
         self.assertEqual(config["run_name"], "ai-tutor-agent-turn")
         self.assertIn("provider:google-genai", config["tags"])
+        self.assertIn("environment:hf-prod", config["tags"])
+        self.assertIn(
+            "deployment:towardsai-tutors-ai-tutor-chatbot.hf.space",
+            config["tags"],
+        )
         self.assertIn("tool:retrieve_tutor_context", config["tags"])
         self.assertIn("tool:run_kb_command", config["tags"])
         self.assertIn("tool:google_search", config["tags"])
         self.assertEqual(config["metadata"]["thread_id"], "thread_123")
         self.assertEqual(config["metadata"]["conversation_id"], "thread_123")
         self.assertEqual(config["metadata"]["message_id"], "message_456")
+        self.assertEqual(config["metadata"]["environment"], "hf-prod")
+        self.assertEqual(
+            config["metadata"]["deployment_host"],
+            "towardsai-tutors-ai-tutor-chatbot.hf.space",
+        )
         self.assertEqual(
             config["metadata"]["available_tools"],
             [