Langsmith tracing

.env.example

@@ -22,6 +22,12 @@ AZURE_API_VERSION=0000-00-00-preview
 LLM_MODEL_NAME=fake-llm-model
 LLM_TEMPERATURE=0.7
 
+##### LANGSMITH TRACING ####
+LANGSMITH_TRACING_ENABLED=False
+LANGSMITH_PROJECT=fake_project
+LANGSMITH_ENDPOINT=https://api.smith.langchain.com
+LANGSMITH_API_KEY=FAKE_LANGSMITH_API_KEY
+
 ##### POSTGRES #########
 # PG_HOST=fake-prod-postgres.example.com
 PG_HOST=fake-dev-postgres.example.com

pyproject.toml

@@ -51,6 +51,7 @@ langchain-mistralai = "^1.1.2"
 langchain-azure-ai = "^1.2.3"
 langgraph = "^1.1.10"
 mistralai = "^2.4.3"
+langsmith = "^0.9.3"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.4.0"

src/app/api/api_v1/endpoints/chat.py

@@ -59,6 +59,26 @@
 }
 
 
+def _build_agent_trace_context(
+    *,
+    endpoint: str,
+    session_id: UUID | None,
+    thread_id: UUID,
+    body: models.AgentContext,
+) -> models.TraceContext:
+    env = settings.ENV
+    return {
+        "endpoint": endpoint,
+        "feature": "chat_agent",
+        "environment": env,
+        "session_id": str(session_id) if session_id else None,
+        "thread_id": str(thread_id),
+        "query_length": len(body.query or ""),
+        "sdg_filter": body.sdg_filter,
+        "corpora": list(body.corpora) if body.corpora else None,
+    }
+
+
 def get_params(body: models.Context) -> models.ContextOut:
     body.sources = body.sources[:7]
 
@@ -400,6 +420,12 @@ async def agent_stream_response(
     try:
         session_id = extract_session_cookie(request)
         thread_id = _resolve_thread_id(body.thread_id)
+        trace_context = _build_agent_trace_context(
+            endpoint="/api/v1/qna/chat/agent_stream",
+            session_id=session_id,
+            thread_id=thread_id,
+            body=body,
+        )
 
         if body.query is None:
             raise EmptyQueryError()
@@ -415,6 +441,7 @@ async def agent_stream_response(
                 data_collection=data_collection,
                 session_id=session_id,
                 thread_id=thread_id,
+                trace_context=trace_context,
             ),
             media_type="text/event-stream",
             headers=SSE_HEADERS,
@@ -457,6 +484,13 @@ async def agent_response(
             logger.info("No thread_id provided. Generating new thread_id.")
             thread_id = uuid.uuid4()
 
+        trace_context = _build_agent_trace_context(
+            endpoint="/api/v1/qna/chat/agent",
+            session_id=session_id,
+            thread_id=thread_id,
+            body=body,
+        )
+
         if body.query is None:
             raise EmptyQueryError()
 
@@ -480,13 +514,15 @@ async def agent_response(
                     sdg_filter=body.sdg_filter,
                     sp=sp,
                     background_tasks=background_tasks,
+                    trace_context=trace_context,
                 )
         else:
             res = await chatfactory.agent_message(
                 query=body.query,
                 corpora=body.corpora,
                 sdg_filter=body.sdg_filter,
                 sp=sp,
+                trace_context=trace_context,
             )
 
         all_docs = []

src/app/api/api_v1/endpoints/chat_utils.py

@@ -83,6 +83,7 @@ async def _stream_agent_with_memory(
     sp: SearchService,
     background_tasks: BackgroundTasks,
     thread_id: UUID,
+    trace_context: models.TraceContext | None = None,
 ) -> AsyncGenerator[dict[str, Any], None]:
     async with await psycopg.AsyncConnection[DictRow].connect(
         db_uri,
@@ -103,6 +104,7 @@ async def _stream_agent_with_memory(
             sp=sp,
             background_tasks=background_tasks,
             streamed_ans=True,
+            trace_context=trace_context,
         )
 
         async for chunk in stream:
@@ -153,6 +155,7 @@ async def _stream_agent_response(
     data_collection: Any,
     session_id: UUID | None,
     thread_id: UUID,
+    trace_context: models.TraceContext | None = None,
 ) -> AsyncGenerator[str, None]:
     final_content = ""
     docs = None
@@ -166,6 +169,7 @@ async def _stream_agent_response(
         sp=sp,
         background_tasks=background_tasks,
         thread_id=thread_id,
+        trace_context=trace_context,
     )
 
     async for chunk in stream:

src/app/core/config.py

@@ -50,6 +50,13 @@ def get_api_version(self) -> dict:
     LLM_TEMPERATURE: float
     ENV: str
 
+    # LANGSMITH / LANGCHAIN TRACING
+    # TBD: migrate Optional/Union annotations to PEP 604 shorthand (X | Y, X | None) in a dedicated refactor.
+    LANGSMITH_TRACING_ENABLED: bool = False
+    LANGSMITH_PROJECT: Optional[str] = None
+    LANGSMITH_ENDPOINT: Optional[str] = None
+    LANGSMITH_API_KEY: Optional[str] = None
+
     # PG
     PG_USER: Optional[str] = None
     PG_PASSWORD: Optional[str] = None

src/app/core/langsmith.py

@@ -0,0 +1,45 @@
+import os
+
+from src.app.core.config import Settings
+from src.app.utils.logger import logger as utils_logger
+
+logger = utils_logger(__name__)
+
+
+def configure_langsmith_tracing(settings: Settings) -> None:
+    """Configure LangSmith tracing for LangChain-based model calls."""
+
+    is_enabled = settings.LANGSMITH_TRACING_ENABLED
+
+    os.environ["LANGSMITH_TRACING"] = "true" if is_enabled else "false"
+
+    if not is_enabled:
+        logger.info("langsmith_tracing_enabled=false")
+        return
+
+    if settings.LANGSMITH_PROJECT:
+        os.environ["LANGCHAIN_PROJECT"] = settings.LANGSMITH_PROJECT
+    else:
+        logger.warning(
+            "langsmith_tracing_enabled=true but LANGSMITH_PROJECT is missing"
+        )
+
+    if settings.LANGSMITH_ENDPOINT:
+        os.environ["LANGCHAIN_ENDPOINT"] = settings.LANGSMITH_ENDPOINT
+    else:
+        logger.warning(
+            "langsmith_tracing_enabled=true but LANGSMITH_ENDPOINT is missing"
+        )
+
+    if settings.LANGSMITH_API_KEY:
+        os.environ["LANGSMITH_API_KEY"] = settings.LANGSMITH_API_KEY
+    else:
+        logger.warning(
+            "langsmith_tracing_enabled=true but LANGSMITH_API_KEY is missing"
+        )
+
+    logger.info(
+        "langsmith_tracing_enabled=true project=%s endpoint=%s",
+        settings.LANGSMITH_PROJECT,
+        settings.LANGSMITH_ENDPOINT,
+    )

src/app/core/lifespan.py

@@ -5,6 +5,7 @@
 from fastapi import FastAPI
 from qdrant_client import AsyncQdrantClient
 
+from src.app.core.langsmith import configure_langsmith_tracing
 from src.app.shared.infra.llm_proxy import LLMProxy
 from src.app.shared.utils.dependencies import get_settings
 from src.app.tutor.service.tutor import init_chat_model
@@ -13,6 +14,7 @@
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     settings = get_settings()
+    configure_langsmith_tracing(settings)
     await init_chat_model(settings)
     app.state.qdrant = AsyncQdrantClient(
         url=settings.QDRANT_HOST,

src/app/models/chat.py

@@ -69,6 +69,17 @@ class AgentContext(SDGFilter):
     corpora: tuple[str, ...] | None = None
 
 
+class TraceContext(TypedDict):
+    endpoint: str
+    feature: str
+    environment: str
+    session_id: str | None
+    thread_id: str
+    query_length: int
+    sdg_filter: list[int] | None
+    corpora: list[str] | None
+
+
 class AgentResponse(BaseModel):
     content: str | None = None
     status: str | None = None