feat: add optional langsmith tracing

.env.example

@@ -81,6 +81,24 @@ HF_TOKEN=your_huggingface_token_here
 # Optional — defaults to 1024
 # LLM_MAX_NEW_TOKENS=1024
 
+# ── LangSmith Tracing (Optional) ────────────────────────
+
+# Enable LangSmith tracing for the backend RAG pipeline.
+# Optional — defaults to False
+# LANGSMITH_TRACING=False
+
+# LangSmith API key.
+# Optional — only needed when LANGSMITH_TRACING=True
+# LANGSMITH_API_KEY=
+
+# LangSmith API endpoint.
+# Optional — defaults to "https://api.smith.langchain.com"
+# LANGSMITH_ENDPOINT=https://api.smith.langchain.com
+
+# LangSmith project name used for traced runs.
+# Optional — defaults to "pdf-assistant-rag"
+# LANGSMITH_PROJECT=pdf-assistant-rag
+
 # ── Embeddings (Optional — defaults shown)──────────────────────────────────────────────
 
 # SentenceTransformer model ID for generating document embeddings.

backend/app/config.py

@@ -54,6 +54,12 @@ class Settings(BaseSettings):
     LLM_MAX_NEW_TOKENS: int = 1024
     LLM_TEMPERATURE: float = 0.3
 
+    # ── LangSmith Tracing (optional) ─────────────────────
+    LANGSMITH_TRACING: bool = False
+    LANGSMITH_API_KEY: str = ""
+    LANGSMITH_ENDPOINT: str = "https://api.smith.langchain.com"
+    LANGSMITH_PROJECT: str = "pdf-assistant-rag"
+
     # ── Reranker ─────────────────────────────────────────
     RERANKER_MODEL: str = "cross-encoder/ms-marco-MiniLM-L-6-v2"
 

backend/app/rag/agent.py

@@ -10,6 +10,7 @@ from huggingface_hub import InferenceClient
 from app.config import get_settings
 from app.rag.retriever import retrieve
 from app.rag.prompts import SYSTEM_PROMPT, RAG_PROMPT_TEMPLATE, GREETING_PROMPT
+from app.rag.tracing import trace_function
 
 logger = logging.getLogger(__name__)
 settings = get_settings()
@@ -65,6 +66,14 @@ def _chat_messages(system: str, user_content: str) -> list:
     ]
 
 
+@trace_function(
+    "generate_answer",
+    metadata_factory=lambda question, user_id, document_id=None: {
+        "user_id": user_id,
+        "document_id": document_id,
+        "llm_model": settings.LLM_MODEL,
+    },
+)
 def generate_answer(
     question: str,
     user_id: str,
@@ -145,6 +154,14 @@ def generate_answer(
     return {"answer": answer, "sources": sources}
 
 
+@trace_function(
+    "generate_answer_stream",
+    metadata_factory=lambda question, user_id, document_id=None: {
+        "user_id": user_id,
+        "document_id": document_id,
+        "llm_model": settings.LLM_MODEL,
+    },
+)
 def generate_answer_stream(
     question: str,
     user_id: str,

backend/app/rag/embeddings.py

@@ -6,6 +6,7 @@ import logging
 from typing import List
 from langchain_huggingface import HuggingFaceEmbeddings
 from app.config import get_settings
+from app.rag.tracing import trace_call
 
 logger = logging.getLogger(__name__)
 settings = get_settings()
@@ -36,10 +37,26 @@ def get_embedding_model() -> HuggingFaceEmbeddings:
 def embed_texts(texts: List[str]) -> List[List[float]]:
     """Embed a batch of texts into vectors."""
     model = get_embedding_model()
-    return model.embed_documents(texts)
+    return trace_call(
+        "embed_texts",
+        lambda: model.embed_documents(texts),
+        run_type="embedding",
+        metadata={
+            "embedding_model": settings.EMBEDDING_MODEL,
+            "text_count": len(texts),
+        },
+    )
 
 
 def embed_query(query: str) -> List[float]:
     """Embed a single query string."""
     model = get_embedding_model()
-    return model.embed_query(query)
+    return trace_call(
+        "embed_query",
+        lambda: model.embed_query(query),
+        run_type="embedding",
+        metadata={
+            "embedding_model": settings.EMBEDDING_MODEL,
+            "query_length": len(query),
+        },
+    )

backend/app/rag/retriever.py

@@ -5,6 +5,7 @@ import logging
 from typing import List, Dict, Any, Optional
 from app.config import get_settings
 from app.rag.embeddings import embed_query
+from app.rag.tracing import trace_function
 from app.rag.vectorstore import query_chunks
 
 logger = logging.getLogger(__name__)
@@ -31,6 +32,17 @@ def get_reranker():
     return _reranker if _reranker != "disabled" else None
 
 
+@trace_function(
+    "retrieve",
+    metadata_factory=lambda query, user_id, document_id=None: {
+        "user_id": user_id,
+        "document_id": document_id,
+        "embedding_model": settings.EMBEDDING_MODEL,
+        "reranker_model": settings.RERANKER_MODEL,
+        "top_k_retrieval": settings.TOP_K_RETRIEVAL,
+        "top_k_rerank": settings.TOP_K_RERANK,
+    },
+)
 def retrieve(
     query: str,
     user_id: str,

backend/app/rag/tracing.py

@@ -0,0 +1,102 @@
+"""
+Optional LangSmith tracing helpers for the RAG pipeline.
+Safe to import even when LangSmith is not installed or configured.
+"""
+import logging
+import os
+from functools import wraps
+from typing import Any, Callable, Optional
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+try:
+    from langsmith import traceable as _langsmith_traceable
+except Exception:  # pragma: no cover - optional dependency safety
+    _langsmith_traceable = None
+
+
+def configure_langsmith() -> bool:
+    """Configure LangSmith environment variables when tracing is enabled."""
+    if not settings.LANGSMITH_TRACING:
+        return False
+
+    if not settings.LANGSMITH_API_KEY:
+        logger.warning("LangSmith tracing enabled but LANGSMITH_API_KEY is not set; tracing disabled.")
+        return False
+
+    os.environ["LANGSMITH_TRACING"] = "true"
+    os.environ["LANGSMITH_API_KEY"] = settings.LANGSMITH_API_KEY
+    os.environ["LANGSMITH_ENDPOINT"] = settings.LANGSMITH_ENDPOINT
+    os.environ["LANGSMITH_PROJECT"] = settings.LANGSMITH_PROJECT
+    return _langsmith_traceable is not None
+
+
+LANGSMITH_ENABLED = configure_langsmith()
+
+
+def _sanitize_metadata(metadata: Optional[dict[str, Any]]) -> dict[str, Any]:
+    return {key: value for key, value in (metadata or {}).items() if value is not None}
+
+
+def _build_traceable(name: str, run_type: str, metadata: Optional[dict[str, Any]] = None):
+    """Build a LangSmith traceable decorator safely across versions."""
+    if _langsmith_traceable is None:
+        return None
+
+    sanitized = _sanitize_metadata(metadata)
+    try:
+        return _langsmith_traceable(
+            name=name,
+            run_type=run_type,
+            metadata=sanitized or None,
+        )
+    except TypeError:
+        return _langsmith_traceable(name=name, run_type=run_type)
+
+
+def trace_call(
+    name: str,
+    fn: Callable[..., Any],
+    *args: Any,
+    run_type: str = "chain",
+    metadata: Optional[dict[str, Any]] = None,
+    **kwargs: Any,
+) -> Any:
+    """Execute a callable with LangSmith tracing when available."""
+    if not LANGSMITH_ENABLED:
+        return fn(*args, **kwargs)
+
+    decorator = _build_traceable(name, run_type, metadata)
+    if decorator is None:
+        return fn(*args, **kwargs)
+
+    traced_fn = decorator(fn)
+    return traced_fn(*args, **kwargs)
+
+
+def trace_function(
+    name: str,
+    *,
+    run_type: str = "chain",
+    metadata_factory: Optional[Callable[..., dict[str, Any]]] = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator wrapper that becomes a no-op when LangSmith is disabled."""
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(fn)
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            metadata = metadata_factory(*args, **kwargs) if metadata_factory else None
+            return trace_call(
+                name,
+                fn,
+                *args,
+                run_type=run_type,
+                metadata=metadata,
+                **kwargs,
+            )
+
+        return wrapped
+
+    return decorator

backend/requirements.txt

@@ -27,6 +27,7 @@ langchain
 langchain-community
 langchain-huggingface
 langchain-text-splitters
+langsmith
 
 # Embeddings & ML
 sentence-transformers