guardianhub 0.1.88__py3-none-any.whl

guardianhub/clients/langfuse/score_evaluation_client.py

@@ -0,0 +1,92 @@
+"""Langfuse evaluation client.
+
+This module provides a client for running evaluations and scoring in Langfuse.
+"""
+
+from __future__ import annotations
+from typing import Optional
+from langfuse import Langfuse
+from guardianhub import get_logger
+from .manager import LangfuseManager
+
+LOGGER = get_logger(__name__)
+
+class EvaluationClient:
+    """Client for Langfuse evaluations."""
+
+    def __init__(
+        self,
+        client: Optional[Langfuse] = None,
+        public_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        host: Optional[str] = None,
+        **kwargs
+    ):
+        """Initialize the EvaluationClient.
+        
+        Args:
+            client: Optional Langfuse client instance. If not provided, will use LangfuseManager.
+            public_key: Langfuse public key. If not provided, will use LANGFUSE_PUBLIC_KEY from environment.
+            secret_key: Langfuse secret key. If not provided, will use LANGFUSE_SECRET_KEY from environment.
+            host: Langfuse host URL. If not provided, will use LANGFUSE_HOST from environment or default.
+            **kwargs: Additional arguments to pass to Langfuse client initialization.
+        """
+        if client is not None:
+            self._client = client
+        else:
+            self._client = LangfuseManager.get_instance(
+                public_key=public_key,
+                secret_key=secret_key,
+                host=host,
+                **kwargs
+            )
+
+    def score_trace(self, trace_id: str, name: str, value: float, comment: Optional[str] = None) -> None:
+        """
+        Scores a trace in Langfuse.
+
+        Args:
+            trace_id: The ID of the trace to score.
+            name: The name of the score (e.g., "user-feedback").
+            value: The score value.
+            comment: An optional comment.
+        """
+        if not self._client:
+            LOGGER.warning("Langfuse client not initialized. Cannot score trace.")
+            return
+
+        try:
+            self._client.score(
+                trace_id=trace_id,
+                name=name,
+                value=value,
+                comment=comment,
+            )
+            LOGGER.info("Successfully scored trace %s with score '%s'", trace_id, name)
+        except Exception as e:
+            LOGGER.error("Failed to score trace %s: %s", trace_id, e)
+
+    def score_span(self, span_id: str, name: str, value: float, comment: Optional[str] = None) -> None:
+        """
+        Scores a span in Langfuse.
+
+        Args:
+            span_id: The ID of the span to score.
+            name: The name of the score.
+            value: The score value.
+            comment: An optional comment.
+        """
+        if not self._client:
+            LOGGER.warning("Langfuse client not initialized. Cannot score span.")
+            return
+
+        try:
+            self._client.score(
+                observation_id=span_id,
+                name=name,
+                value=value,
+                comment=comment,
+            )
+            LOGGER.info("Successfully scored span %s with score '%s'", span_id, name)
+        except Exception as e:
+            LOGGER.error("Failed to score span %s: %s", span_id, e)

guardianhub/clients/langfuse/tracing_client.py

@@ -0,0 +1,250 @@
+"""Langfuse tracing client for observability.
+
+This module provides a client for tracing and logging.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any, Dict, Optional
+
+from langfuse import Langfuse, LangfuseSpan
+from langfuse.api.client import TraceClient as Trace
+
+from guardianhub import get_logger
+from .manager import LangfuseManager
+
+LOGGER = get_logger(__name__)
+
+
+class TracingClient:
+    """Client for Langfuse tracing, spans, and events."""
+    _current_trace: ContextVar[Optional[Trace]] = ContextVar("_current_trace", default=None)
+    _current_span: ContextVar[Optional[LangfuseSpan]] = ContextVar("_current_span", default=None)
+
+    def __init__(
+        self,
+        client: Optional[Langfuse] = None,
+        public_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        host: Optional[str] = None,
+        **kwargs
+    ):
+        """Initialize the TracingClient.
+        
+        Args:
+            client: Optional Langfuse client instance. If not provided, will use LangfuseManager.
+            public_key: Langfuse public key. If not provided, will use LANGFUSE_PUBLIC_KEY from environment.
+            secret_key: Langfuse secret key. If not provided, will use LANGFUSE_SECRET_KEY from environment.
+            host: Langfuse host URL. If not provided, will use LANGFUSE_HOST from environment or default.
+            **kwargs: Additional arguments to pass to Langfuse client initialization.
+        """
+        if client is not None:
+            self._client = client
+        else:
+            self._client = LangfuseManager.get_instance(
+                public_key=public_key,
+                secret_key=secret_key,
+                host=host,
+                **kwargs
+            )
+        self.default_trace_tags: Dict[str, Any] = {}
+        self.default_span_tags: Dict[str, Any] = {}
+
+    @property
+    def is_initialized(self) -> bool:
+        return self._client is not None
+
+    def set_default_trace_tags(self, tags: Dict[str, Any]) -> None:
+        self.default_trace_tags.update(tags)
+
+    def set_default_span_tags(self, tags: Dict[str, Any]) -> None:
+        self.default_span_tags.update(tags)
+
+    def get_current_trace(self) -> Optional[Trace]:
+        return self._current_trace.get()
+
+    def get_current_span(self) -> Optional[LangfuseSpan]:
+        """Get the current active span.
+        
+        Returns:
+            Optional[LangfuseSpan]: The current active span, or None if no span is active.
+        """
+        return self._current_span.get()
+
+    def start_trace(
+        self,
+        name: str,
+        tags: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Optional[Trace]:
+        if not self.is_initialized:
+            LOGGER.debug("Langfuse client not initialized. Skipping trace creation.")
+            return None
+        
+        if not name or not isinstance(name, str):
+            raise ValueError("Trace name must be a non-empty string")
+            
+        merged_tags = {**self.default_trace_tags, **(tags or {})}
+        
+        try:
+            trace = self._create_trace(
+                name=name, 
+                tags=merged_tags, 
+                metadata=metadata or {},
+                **kwargs
+            )
+            self._current_trace.set(trace)
+            LOGGER.debug("Started trace: %s", name)
+            return trace
+        except Exception as e:
+            LOGGER.error("Failed to start trace '%s': %s", name, str(e), exc_info=True)
+            return None
+
+    def end_trace(self, trace: Optional[Trace] = None) -> None:
+        trace_to_end = trace or self.get_current_trace()
+        if not trace_to_end:
+            LOGGER.debug("No active trace to end")
+            return
+            
+        try:
+            self._end_trace(trace_to_end)
+            LOGGER.debug("Ended trace: %s", getattr(trace_to_end, 'id', 'unknown'))
+        except Exception as e:
+            LOGGER.exception("Error ending trace: %s", str(e))
+        finally:
+            if self.get_current_trace() is trace_to_end:
+                self._current_trace.set(None)
+                self._current_span.set(None)
+
+    def start_span(
+        self, 
+        name: str, 
+        tags: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Optional[LangfuseSpan]:
+        if not self.is_initialized:
+            LOGGER.debug("Langfuse client not initialized. Skipping span creation.")
+            return None
+
+        if not name or not isinstance(name, str):
+            raise ValueError("Span name must be a non-empty string")
+            
+        trace = self.get_current_trace()
+        
+        if not trace:
+            trace_name = f"auto-trace-{name}"
+            LOGGER.debug("No active trace found. Creating new trace: %s", trace_name)
+            trace = self.start_trace(name=trace_name, tags=tags, metadata=metadata)
+            if not trace:
+                LOGGER.error("Failed to auto-create trace for span '%s'", name)
+                return None
+
+        merged_tags = {**self.default_span_tags, **(tags or {})}
+
+        try:
+            span = self._create_span(trace, name, merged_tags, metadata or {}, **kwargs)
+            self._current_span.set(span)
+            LOGGER.debug("Started span '%s' in trace %s", name, getattr(trace, 'id', 'unknown'))
+            return span
+        except Exception as e:
+            LOGGER.error("Failed to start span '%s': %s", name, str(e), exc_info=True)
+            return None
+
+    def end_span(self, span: Optional[LangfuseSpan] = None) -> None:
+        span_to_end = span or self.get_current_span()
+        if not span_to_end:
+            LOGGER.debug("No active span to end")
+            return
+            
+        try:
+            self._end_span(span_to_end)
+            LOGGER.debug("Ended span: %s", getattr(span_to_end, 'id', 'unknown'))
+        except Exception as e:
+            LOGGER.exception("Error ending span: %s", str(e))
+        finally:
+            if self.get_current_span() is span_to_end:
+                self._current_span.set(None)
+
+    def start_agent_trace(self, agent_name: str, agent_version: Optional[str] = None,
+                          task_type: Optional[str] = None, domain: Optional[str] = None,
+                          metadata: Optional[Dict[str, Any]] = None) -> Optional[Trace]:
+        tags = {"agent_name": agent_name}
+        if agent_version:
+            tags["agent_version"] = agent_version
+        if task_type:
+            tags["task_type"] = task_type
+        if domain:
+            tags["domain"] = domain
+
+        return self.start_trace(name=f"agent:{agent_name}", tags=tags, metadata=metadata)
+
+    def log_agent_step(self, step_type: str, input_data: Optional[Any] = None, output_data: Optional[Any] = None,
+                       metadata: Optional[Dict[str, Any]] = None) -> Optional[LangfuseSpan]:
+        metadata = metadata or {}
+        metadata.update({"input": input_data, "output": output_data})
+        return self.start_span(name=f"step:{step_type}", tags={"step_type": step_type}, metadata=metadata)
+
+    def log_tool_call(self, tool_name: str, status: str = "success", error: Optional[str] = None,
+                      metadata: Optional[Dict[str, Any]] = None) -> Optional[LangfuseSpan]:
+        metadata = metadata or {}
+        if error:
+            metadata["error_message"] = error
+        span = self.start_span(name=f"tool:{tool_name}", tags={"tool_name": tool_name, "tool_status": status},
+                               metadata=metadata)
+        if span:
+            self.end_span(span)
+        return span
+
+    def log_reflection_event(self, event_name: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        trace = self.get_current_trace()
+        if not trace:
+            LOGGER.warning("No active trace for reflection event %s", event_name)
+            return
+        try:
+            trace.event(name=event_name, metadata=metadata or {})
+        except Exception:
+            LOGGER.exception("Failed to log reflection event")
+
+    def _create_trace(
+        self, 
+        name: str, 
+        tags: Dict[str, Any], 
+        metadata: Dict[str, Any],
+        **kwargs
+    ) -> Trace:
+        if not self._client:
+            raise RuntimeError("Langfuse client is not initialized")
+        
+        tag_list = [f"{k}:{v}" for k, v in tags.items()]
+        
+        return self._client.trace(
+            name=name,
+            metadata=metadata,
+            tags=tag_list,
+            **kwargs
+        )
+
+    def _end_trace(self, trace: Trace) -> None:
+        trace.end()
+
+    def _create_span(
+        self, 
+        trace: Trace,
+        name: str, 
+        tags: Dict[str, Any], 
+        metadata: Dict[str, Any],
+        **kwargs
+    ) -> LangfuseSpan:
+        tag_list = [f"{k}:{v}" for k, v in tags.items()]
+        return trace.span(
+            name=name,
+            metadata=metadata,
+            tags=tag_list,
+            **kwargs
+        )
+
+    def _end_span(self, span: LangfuseSpan) -> None:
+        span.end()

guardianhub/clients/langfuse_client.py

@@ -0,0 +1,63 @@
+"""Main Langfuse client for Guardian Hub SDK.
+
+This module provides a centralized client that acts as a facade for various
+Langfuse functionalities, including tracing, prompt management, and evaluations.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .langfuse.score_evaluation_client import EvaluationClient
+from .langfuse.manager import LangfuseManager
+from .langfuse.prompt_client import PromptClient
+from .langfuse.tracing_client import TracingClient
+
+from guardianhub import get_logger
+
+LOGGER = get_logger(__name__)
+
+
+class LangfuseClient:
+    """A facade client for Langfuse, providing access to tracing, prompts, and evaluations.
+    
+    This client centralizes access to Langfuse functionalities by using a manager
+    to handle the singleton connection.
+
+    Args:
+        public_key: Langfuse public key (optional, can be set via LANGFUSE_PUBLIC_KEY env var).
+        secret_key: Langfuse secret key (optional, can be set via LANGFUSE_SECRET_KEY env var).
+        host: Langfuse host URL (optional, can be set via LANGFUSE_HOST env var).
+        **kwargs: Additional arguments to pass to the Langfuse client constructor.
+    """
+
+    def __init__(
+        self,
+        public_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        host: Optional[str] = None,
+        **kwargs
+    ):
+        """Initialize the main Langfuse client and its sub-clients."""
+        # Get the singleton Langfuse instance from the manager
+        self._client = LangfuseManager.get_instance(
+            public_key=public_key,
+            secret_key=secret_key,
+            host=host,
+            **kwargs
+        )
+        
+        # Initialize specialized clients, passing the core client instance
+        self.tracing = TracingClient(self._client)
+        self.prompts = PromptClient(self._client)
+        self.evaluations = EvaluationClient(self._client)
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if the core Langfuse client is initialized."""
+        return self._client is not None
+
+    def flush(self) -> None:
+        """Flush the Langfuse client to ensure all buffered data is sent."""
+        LangfuseManager.flush()

guardianhub/clients/llm_client.py

@@ -0,0 +1,144 @@
+# llm/llm_service.py
+import json
+from typing import Dict, Any, Optional, Type, TypeVar, List, Union
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from guardianhub import get_logger
+
+logger = get_logger(__name__)
+from guardianhub.config import settings
+
+T = TypeVar('T', bound=BaseModel)
+
+class LLMClient:
+    """Unified client for LLM interactions with structured output support."""
+
+    def __init__(self, base_url: str, api_key: Optional[str] = None):
+        self.base_url = base_url.rstrip('/')
+        self.client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"} if api_key else {},
+            timeout=240.0
+        )
+
+    async def chat_completion(
+            self,
+            messages: List[Dict[str, str]],
+            model_key: str = None,
+            temperature: Optional[float] = None,
+            max_tokens: Optional[int] = None,
+            response_format: Optional[Dict[str, str]] = None,
+            response_model: Optional[Type[T]] = None,
+            **kwargs
+    ) -> Union[Dict[str, Any], T]:
+        """
+        Send a chat completion request to the LLM service.
+
+        Args:
+            messages: List of message dictionaries with 'role' and 'content'
+            model_key: The model key to use
+            temperature: Sampling temperature (0-2)
+            max_tokens: Maximum number of tokens to generate
+            response_format: Optional format specification for the response
+            response_model: Optional Pydantic model for structured output
+            **kwargs: Additional arguments to pass to the API
+
+        Returns:
+            Dict containing the API response or an instance of response_model if provided
+
+        Raises:
+            RuntimeError: If the API request fails
+            ValidationError: If response_model is provided and the response doesn't match the schema
+        """
+        # Set defaults from settings if not provided
+        model_key = model_key or getattr(settings.llm, 'model_key', 'default')
+        temperature = temperature if temperature is not None else getattr(settings.llm, 'temperature', 0.7)
+        max_tokens = max_tokens if max_tokens is not None else getattr(settings.llm, 'max_tokens', 1000)
+
+        # Prepare the base payload
+        payload = {
+            "model": getattr(settings.llm, 'model_name', 'gpt-3.5-turbo'),
+            "model_key": model_key,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            **{k: v for k, v in kwargs.items() if v is not None}
+        }
+
+        # For structured output, include the schema in the request
+        if response_model is not None:
+            payload["response_schema"] = response_model.model_json_schema()
+            payload["response_model"] = response_model.__name__
+
+        try:
+            response = await self.client.post(
+                "/v1/chat/completions",
+                json=payload,
+                timeout=360.0
+            )
+            response.raise_for_status()
+            response_data = response.json()
+
+            logger.debug(f"Received Response Data: {response_data}")
+
+            if "choices" in response_data:
+                content = response_data["choices"][0]["message"].get("content")
+
+                if content and isinstance(content, str):
+                    try:
+                        content = json.loads(content)
+                    except json.JSONDecodeError:
+                        pass
+
+                if response_model and content:
+                    try:
+                        return response_model.parse_obj(content)
+                    except ValidationError as e:
+                        logger.error(f"Response validation failed: {e}")
+                        logger.debug(f"Response content: {content}")
+                        raise
+
+                return content or response_data
+
+            return response_data
+
+        except httpx.HTTPStatusError as e:
+            error_msg = "LLM API error ({}): {}".format(e.response.status_code, e.response.text)
+            logger.error(error_msg)
+            raise RuntimeError("LLM service error: {}".format(error_msg)) from e
+        except Exception as e:
+            logger.error("Unexpected error: {}".format(str(e)), exc_info=True)
+            raise RuntimeError("LLM client error: {}".format(str(e))) from e
+
+    async def generate_structured(
+            self,
+            messages: List[Dict[str, str]],
+            response_model: Type[T],
+            **kwargs
+    ) -> T:
+        """
+        Generate a structured response using the specified model.
+
+        Args:
+            messages: List of message dictionaries with 'role' and 'content'
+            response_model: Pydantic model class for the expected output structure
+            **kwargs: Additional arguments to pass to chat_completion
+
+        Returns:
+            An instance of the provided response_model with the generated content
+
+        Raises:
+            RuntimeError: If the API request fails
+            ValidationError: If the response doesn't match the schema
+        """
+        return await self.chat_completion(
+            messages=messages,
+            response_model=response_model,
+            **kwargs
+        )
+
+    async def close(self):
+        """Close the HTTP client."""
+        await self.client.aclose()