Implement LangSmith tracing for enhanced monitoring and debugging (#13)

Author: Joelit0

.env.example

@@ -26,4 +26,12 @@ BACKOFFICE_DEFAULT_ID_ESTADO=1
 # Wizard guardrails
 WIZARD_DETECT_JAILBREAK_ENABLED=true
 WIZARD_DETECT_JAILBREAK_THRESHOLD=0.9
+
 # GUARDRAILS_HUB_TOKEN=coloca_tu_token_del_guardrails_hub
+OPENAI_API_KEY=YOUR_API_KEY_HERE
+
+# LangSmith configuration
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
+LANGCHAIN_API_KEY=YOUR_LANGCHAIN_API_KEY_HERE
+LANGCHAIN_PROJECT=YOUR_LANGCHAIN_PROJECT_NAME_HERE

Dockerfile

@@ -24,8 +24,8 @@ RUN apt-get update \
 
 # Install Python dependencies with uv
 COPY requirements.txt .
-RUN pip install --no-cache-dir "uv==${UV_VERSION}" \
-    && uv pip install --system -r requirements.txt
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
 
 # Copy project
 COPY . .

app/agents/faq.py

@@ -10,11 +10,16 @@
 import logging
 import os
 from pathlib import Path
+from typing import Any
 
+import numpy as np
 import yaml
+from jinja2 import Environment, FileSystemLoader
 from langchain_core.messages import AIMessage, SystemMessage
 from langchain_openai import ChatOpenAI
 from langgraph.prebuilt import ToolNode
+from langsmith import traceable
+from langchain_core.tracers.context import tracing_v2_enabled
 
 from .base import AgentNode
 from ..db.config.database import get_async_session
@@ -32,14 +37,23 @@
 
 class FAQAgent(AgentNode):
     """Answers frequently-asked questions using a tool-calling loop."""
-
-    name: str = _config["name"]
-    description: str = _config["description"]
+    
+    name = "faq"
+    description = "Answers frequently asked questions about Ithaka using the knowledge base"
 
     def __init__(self):
+        super().__init__()
+        
         model_name = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
         model_cfg = _config["model"]
 
+        # LangSmith configuration
+        self.tracing_enabled = os.getenv("LANGCHAIN_TRACING_V2", "false").lower() == "true"
+        self.project_name = os.getenv("LANGCHAIN_PROJECT", "ithaka-project")
+        
+        if self.tracing_enabled:
+            logger.info(f"LangSmith tracing enabled for FAQ agent in project: {self.project_name}")
+
         self.llm = ChatOpenAI(
             model=model_name,
             temperature=model_cfg["temperature_contextual"],
@@ -50,7 +64,15 @@ def __init__(self):
         self.system_message = SystemMessage(
             content=_config["system_prompts"]["contextual"]
         )
-
+        
+        # Cargar templates Jinja2 para uso futuro si es necesario
+        template_dir = Path(__file__).parent / "prompts"
+        env = Environment(loader=FileSystemLoader(template_dir))
+        self.contextual_template = env.get_template("faq_contextual.j2")
+        self.no_results_template = env.get_template("faq_no_results.j2")
+        self.system_template = env.get_template("faq_system_contextual.j2")
+
+    @traceable(run_type="chain")
     async def __call__(self, state: ConversationState) -> ConversationState:
         """Run the tool-calling loop and return the updated conversation state."""
 
@@ -112,6 +134,7 @@ async def __call__(self, state: ConversationState) -> ConversationState:
     # Internal helpers
     # ------------------------------------------------------------------
 
+    @traceable(run_type="chain")
     async def _tool_calling_loop(
         self,
         messages: list,
@@ -141,6 +164,8 @@ async def _tool_calling_loop(
 faq_agent = FAQAgent()
 
 
+# Función para usar en el grafo LangGraph
+@traceable(run_type="chain")
 async def handle_faq_query(state: ConversationState) -> ConversationState:
     """Wrapper function for LangGraph."""
     return await faq_agent(state)

app/agents/supervisor.py

@@ -12,6 +12,8 @@
 import yaml
 from jinja2 import Environment, FileSystemLoader
 from openai import AsyncOpenAI
+from langsmith import traceable
+from langchain_core.tracers.context import tracing_v2_enabled
 
 from ..graph.agent_descriptions import (
     DEFAULT_AGENT,
@@ -38,11 +40,19 @@ def __init__(self):
 
         self.client = AsyncOpenAI(api_key=api_key)
         self.model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+        
+        # LangSmith configuration
+        self.tracing_enabled = os.getenv("LANGCHAIN_TRACING_V2", "false").lower() == "true"
+        self.project_name = os.getenv("LANGCHAIN_PROJECT", "ithaka-project")
+        
+        if self.tracing_enabled:
+            logger.info(f"LangSmith tracing enabled for Supervisor agent in project: {self.project_name}")
 
     # ------------------------------------------------------------------
     # Public interface used by the LangGraph workflow
     # ------------------------------------------------------------------
 
+    @traceable(run_type="chain")
     async def route_message(self, state: ConversationState) -> ConversationState:
         """Analiza el mensaje del usuario y decide el routing."""
 
@@ -95,6 +105,7 @@ def decide_next_agent(self, state: ConversationState) -> str:
     # Internal helpers
     # ------------------------------------------------------------------
 
+    @traceable(run_type="llm")
     async def _route_by_descriptions(self, message: str, messages: list) -> str:
         """Usa el LLM para elegir el agente cuya descripción mejor
         coincide con la intención del usuario."""
@@ -181,11 +192,13 @@ def _route_to(state: ConversationState, agent: str) -> ConversationState:
 supervisor_agent = SupervisorAgent()
 
 
+@traceable(run_type="chain")
 async def route_message(state: ConversationState) -> ConversationState:
     """Función wrapper para LangGraph."""
     return await supervisor_agent.route_message(state)
 
 
+@traceable(run_type="chain")
 def decide_next_agent_wrapper(state: ConversationState) -> str:
     """Función wrapper para routing condicional en LangGraph."""
     return supervisor_agent.decide_next_agent(state)

app/graph/workflow.py

@@ -3,13 +3,17 @@
 """
 
 import logging
+import os
 from typing import Any
 import uuid
 
 from langgraph.checkpoint.memory import InMemorySaver
 from langgraph.graph import StateGraph, END
 from langgraph.graph.state import CompiledStateGraph
 from langchain_core.messages import HumanMessage
+from langsmith import traceable
+from langchain_core.tracers.context import tracing_v2_enabled
+from langchain_core.tracers.langchain import LangChainTracer
 
 from .agent_descriptions import ROUTABLE_AGENTS
 from .state import ConversationState
@@ -25,6 +29,13 @@ class IthakaWorkflow:
     """Workflow principal que maneja toda la lógica de conversación"""
 
     def __init__(self):
+        # Initialize LangSmith tracing
+        self.tracing_enabled = os.getenv("LANGCHAIN_TRACING_V2", "false").lower() == "true"
+        self.project_name = os.getenv("LANGCHAIN_PROJECT", "ithaka-project")
+        
+        if self.tracing_enabled:
+            logger.info(f"LangSmith tracing enabled for project: {self.project_name}")
+        
         self.graph = self._build_graph()
 
     def _build_graph(self) -> CompiledStateGraph:
@@ -59,6 +70,7 @@ def _build_graph(self) -> CompiledStateGraph:
         workflow.add_edge("faq", END)
 
         # Compilar el grafo
+        # Usar configuración básica para el checkpointer
         return workflow.compile(checkpointer=InMemorySaver())
 
     def _create_initial_state(
@@ -105,6 +117,7 @@ def _create_initial_state(
 
         return base_state
 
+    @traceable(run_type="chain")
     async def process_message(
         self,
         user_message: str,
@@ -142,8 +155,24 @@ async def process_message(
             )
 
             logger.info(f"Processing message: {user_message[:50]}...")
-            config = {"configurable": {"thread_id": thread_id}}
-            result = await self.graph.ainvoke(initial_state, config=config)
+            
+            # Use tracing context if enabled
+            # Generar un ID único para esta conversación
+            conversation_id = str(uuid.uuid4()) if thread_id == "default" else thread_id
+            
+            # Configurar parámetros para el checkpointer
+            config_params = {
+                "configurable": {
+                    "thread_id": conversation_id,
+                    "checkpoint_ns": "ithaka"
+                }
+            }
+            
+            if self.tracing_enabled:
+                with tracing_v2_enabled(project_name=self.project_name):
+                    result = await self.graph.ainvoke(initial_state, config=config_params)
+            else:
+                result = await self.graph.ainvoke(initial_state, config=config_params)
 
             logger.debug(f"[WORKFLOW] Graph result keys: {list(result.keys())}")
             logger.debug(f"[WORKFLOW] Result current_agent: {result.get('current_agent')}")

app/services/embedding_service.py

@@ -6,6 +6,8 @@
 from openai import AsyncOpenAI
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
+from langsmith import traceable
+from langchain_core.tracers.context import tracing_v2_enabled
 
 from ..db.models import FAQEmbedding
 
@@ -16,11 +18,21 @@ class EmbeddingService:
     """Servicio para generar y gestionar embeddings usando OpenAI"""
 
     def __init__(self):
+        # Initialize OpenAI client
         self.client = AsyncOpenAI(api_key=os.getenv("OPENAI_API_KEY"))
         self.model = os.getenv("OPENAI_EMBEDDING_MODEL",
                                "text-embedding-3-small")
         self.dimension = int(os.getenv("EMBEDDING_DIMENSION", "1536"))
-
+        
+        # Enable LangSmith tracing
+        self.tracing_enabled = os.getenv("LANGCHAIN_TRACING_V2", "false").lower() == "true"
+        self.project_name = os.getenv("LANGCHAIN_PROJECT", "ithaka-project")
+        
+        logger.info(f"Embedding Service initialized with model: {self.model}")
+        if self.tracing_enabled:
+            logger.info(f"LangSmith tracing enabled for project: {self.project_name}")
+
+    @traceable(run_type="embedding")
     async def generate_embedding(self, text: str) -> List[float]:
         """Genera embedding para un texto dado"""
         try:
@@ -33,6 +45,20 @@ async def generate_embedding(self, text: str) -> List[float]:
             logger.error(f"Error generating embedding: {e}")
             raise
 
+    @traceable(run_type="embedding")
+    async def generate_batch_embeddings(self, texts: List[str]) -> List[List[float]]:
+        """Genera embeddings para múltiples textos en batch"""
+        try:
+            response = await self.client.embeddings.create(
+                model=self.model,
+                input=texts
+            )
+            return [data.embedding for data in response.data]
+        except Exception as e:
+            logger.error(f"Error generating batch embeddings: {e}")
+            raise
+
+    @traceable(run_type="retriever")
     async def search_similar_faqs(
             self,
             query: str,
@@ -74,6 +100,7 @@ async def search_similar_faqs(
             logger.error(f"Error searching similar FAQs: {e}")
             return []
 
+    @traceable(run_type="tool")
     async def add_faq_embedding(
             self,
             question: str,

requirements.txt

@@ -11,13 +11,14 @@ asyncpg==0.30.0
 pgvector==0.4.1
 
 # AI and LLM
-openai==1.99.1
-langchain-openai
+openai==1.104.2
+langchain-openai==0.3.33
 langgraph==0.2.76
 langgraph-checkpoint==2.1.1
 langgraph-sdk==0.1.74
 guardrails-ai>=0.5.10
 rich<14
+langsmith==0.3.45
 
 # Data validation and serialization
 pydantic==2.11.7
@@ -36,7 +37,7 @@ websockets==15.0.1
 twilio==8.13.0
 
 # Numerical computing (used in embeddings)
-numpy==2.3.2
+numpy<2.0.0,>=1.26.2
 
 # JWT authentication
 PyJWT>=2.8.0