fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/core/logging/__init__.py

@@ -0,0 +1,5 @@
+"""Logging module for MCP Agent."""
+
+from fast_agent.core.logging.logger import Logger, LoggingConfig, get_logger
+
+__all__ = ["Logger", "LoggingConfig", "get_logger"]

fast_agent/core/logging/events.py

@@ -0,0 +1,138 @@
+"""
+Events and event filters for the logger module for the MCP Agent
+"""
+
+import logging
+import random
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+EventType = Literal["debug", "info", "warning", "error", "progress"]
+"""Broad categories for events (severity or role)."""
+
+
+class EventContext(BaseModel):
+    """
+    Stores correlation or cross-cutting data (workflow IDs, user IDs, etc.).
+    Also used for distributed environments or advanced logging.
+    """
+
+    session_id: str | None = None
+    workflow_id: str | None = None
+    # request_id: str | None = None
+    # parent_event_id: str | None = None
+    # correlation_id: str | None = None
+    # user_id: str | None = None
+
+    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+
+
+class Event(BaseModel):
+    """
+    Core event structure. Allows both a broad 'type' (EventType)
+    and a more specific 'name' string for domain-specific labeling (e.g. "ORDER_PLACED").
+    """
+
+    type: EventType
+    name: str | None = None
+    namespace: str
+    message: str
+    timestamp: datetime = Field(default_factory=datetime.now)
+    data: dict[str, Any] = Field(default_factory=dict)
+    context: EventContext | None = None
+
+    # For distributed tracing
+    span_id: str | None = None
+    trace_id: str | None = None
+
+    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+
+
+class EventFilter(BaseModel):
+    """
+    Filter events by:
+      - allowed EventTypes (types)
+      - allowed event 'names'
+      - allowed namespace prefixes
+      - a minimum severity level (DEBUG < INFO < WARNING < ERROR)
+    """
+
+    types: set[EventType] = Field(default_factory=set)
+    names: set[str] = Field(default_factory=set)
+    namespaces: set[str] = Field(default_factory=set)
+    min_level: EventType | None = "debug"
+
+    def matches(self, event: Event) -> bool:
+        """
+        Check if an event matches this EventFilter criteria.
+        """
+        # 1) Filter by broad event type
+        if self.types:
+            if event.type not in self.types:
+                return False
+
+        # 2) Filter by custom event name
+        if self.names:
+            if not event.name or event.name not in self.names:
+                return False
+
+        # 3) Filter by namespace prefix
+        if self.namespaces and not any(event.namespace.startswith(ns) for ns in self.namespaces):
+            return False
+
+        # 4) Minimum severity
+        if self.min_level:
+            level_map: dict[EventType, int] = {
+                "debug": logging.DEBUG,
+                "info": logging.INFO,
+                "warning": logging.WARNING,
+                "error": logging.ERROR,
+            }
+
+            min_val = level_map.get(self.min_level, logging.DEBUG)
+            event_val = level_map.get(event.type, logging.DEBUG)
+            if event_val < min_val:
+                return False
+
+        return True
+
+
+class SamplingFilter(EventFilter):
+    """
+    Random sampling on top of base filter.
+    Only pass an event if it meets the base filter AND random() < sample_rate.
+    """
+
+    sample_rate: float = 0.1
+    """Fraction of events to pass through"""
+
+    def matches(self, event: Event) -> bool:
+        if not super().matches(event):
+            return False
+        return random.random() < self.sample_rate
+
+
+class StreamingExclusionFilter(EventFilter):
+    """
+    Event filter that excludes streaming progress events from logs.
+    This prevents token count updates from flooding the logs when info level is enabled.
+    """
+
+    def matches(self, event: Event) -> bool:
+        # First check if it passes the base filter
+        if not super().matches(event):
+            return False
+
+        # Exclude events with "Streaming progress" message
+        if event.message == "Streaming progress":
+            return False
+
+        # Also check for events with progress_action = STREAMING in data
+        if event.data and isinstance(event.data.get("data"), dict):
+            event_data = event.data["data"]
+            if event_data.get("progress_action") == "Streaming":
+                return False
+
+        return True

fast_agent/core/logging/json_serializer.py

@@ -0,0 +1,164 @@
+import dataclasses
+import inspect
+import os
+import warnings
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from typing import Any, Iterable
+from uuid import UUID
+
+import httpx
+
+from fast_agent.core.logging import logger
+
+
+class JSONSerializer:
+    """
+    A robust JSON serializer that handles various Python objects by attempting
+    different serialization strategies recursively.
+    """
+
+    MAX_DEPTH = 99  # Maximum recursion depth
+
+    # Fields that are likely to contain sensitive information
+    SENSITIVE_FIELDS = {
+        "api_key",
+        "secret",
+        "password",
+        "token",
+        "auth",
+        "private_key",
+        "client_secret",
+        "access_token",
+        "refresh_token",
+    }
+
+    def __init__(self) -> None:
+        # Set of already processed objects to prevent infinite recursion
+        self._processed_objects: set[int] = set()
+        # Check if secrets should be logged in full
+        self._log_secrets = os.getenv("LOG_SECRETS", "").upper() == "TRUE"
+
+    def _redact_sensitive_value(self, value: str) -> str:
+        """Redact sensitive values to show only first 10 chars."""
+        if not value or not isinstance(value, str):
+            return value
+        if self._log_secrets:
+            return value
+        if len(value) <= 10:
+            return value + "....."
+        return value[:10] + "....."
+
+    def serialize(self, obj: Any) -> Any:
+        """Main entry point for serialization."""
+        # Reset processed objects for new serialization
+        self._processed_objects.clear()
+        return self._serialize_object(obj, depth=0)
+
+    def _is_sensitive_key(self, key: str) -> bool:
+        """Check if a key likely contains sensitive information."""
+        key = str(key).lower()
+        return any(sensitive in key for sensitive in self.SENSITIVE_FIELDS)
+
+    def _serialize_object(self, obj: Any, depth: int = 0) -> Any:
+        """Recursively serialize an object using various strategies."""
+        # Handle None
+        if obj is None:
+            return None
+
+        if depth == 0:
+            self._parent_obj = obj
+        # Check depth
+        if depth > self.MAX_DEPTH:
+            warnings.warn(
+                f"Maximum recursion depth ({self.MAX_DEPTH}) exceeded while serializing object of type {type(obj).__name__} parent: {type(self._parent_obj).__name__}"
+            )
+            return str(obj)
+
+        # Prevent infinite recursion
+        obj_id = id(obj)
+        if obj_id in self._processed_objects:
+            return str(obj)
+        self._processed_objects.add(obj_id)
+
+        # Try different serialization strategies in order
+        try:
+            if isinstance(obj, httpx.Response):
+                return f"<httpx.Response [{obj.status_code}] {obj.url}>"
+
+            if isinstance(obj, logger.Logger):
+                return "<logging: logger>"
+
+            # Basic JSON-serializable types
+            if isinstance(obj, (str, int, float, bool)):
+                return obj
+
+            # Handle common built-in types
+            if isinstance(obj, (datetime, date)):
+                return obj.isoformat()
+            if isinstance(obj, (Decimal, UUID)):
+                return str(obj)
+            if isinstance(obj, Path):
+                return str(obj)
+            if isinstance(obj, Enum):
+                return obj.value
+
+            # Handle callables
+            if callable(obj):
+                return f"<callable: {obj.__name__}>"
+
+            # Handle Pydantic models
+            if hasattr(obj, "model_dump"):  # Pydantic v2
+                return self._serialize_object(obj.model_dump())
+            if hasattr(obj, "dict"):  # Pydantic v1
+                return self._serialize_object(obj.dict())
+
+            # Handle dataclasses
+            if dataclasses.is_dataclass(obj):
+                return self._serialize_object(dataclasses.asdict(obj))
+
+            # Handle objects with custom serialization method
+            if hasattr(obj, "to_json"):
+                return self._serialize_object(obj.to_json())
+            if hasattr(obj, "to_dict"):
+                return self._serialize_object(obj.to_dict())
+
+            # Handle dictionaries with sensitive data redaction
+            if isinstance(obj, dict):
+                return {
+                    str(key): self._redact_sensitive_value(value)
+                    if self._is_sensitive_key(key)
+                    else self._serialize_object(value, depth + 1)
+                    for key, value in obj.items()
+                }
+
+            # Handle iterables (lists, tuples, sets)
+            if isinstance(obj, Iterable) and not isinstance(obj, (str, bytes)):
+                return [self._serialize_object(item, depth + 1) for item in obj]
+
+            # Handle objects with __dict__
+            if hasattr(obj, "__dict__"):
+                return self._serialize_object(obj.__dict__, depth + 1)
+
+            # Handle objects with attributes
+            if inspect.getmembers(obj):
+                return {
+                    name: self._redact_sensitive_value(value)
+                    if self._is_sensitive_key(name)
+                    else self._serialize_object(value, depth + 1)
+                    for name, value in inspect.getmembers(obj)
+                    if not name.startswith("_") and not inspect.ismethod(value)
+                }
+
+            # Fallback: convert to string
+            return str(obj)
+
+        except Exception as e:
+            # If all serialization attempts fail, return string representation
+            return f"<unserializable: {type(obj).__name__}, error: {str(e)}>"
+
+    def __call__(self, obj: Any) -> Any:
+        """Make the serializer callable."""
+        return self.serialize(obj)

fast_agent/core/logging/listeners.py

@@ -0,0 +1,309 @@
+"""
+Listeners for the logger module of MCP Agent.
+"""
+
+import asyncio
+import logging
+import time
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fast_agent.event_progress import ProgressEvent
+
+from fast_agent.core.logging.events import Event, EventFilter, EventType
+
+
+def convert_log_event(event: Event) -> "ProgressEvent | None":
+    """Convert a log event to a progress event if applicable."""
+
+    # Import at runtime to avoid circular imports
+    from fast_agent.event_progress import ProgressAction, ProgressEvent
+
+    # Check to see if there is any additional data
+    if not event.data:
+        return None
+
+    event_data = event.data.get("data")
+    if not isinstance(event_data, dict):
+        return None
+
+    raw_action = event_data.get("progress_action")
+    if not raw_action:
+        return None
+
+    # Coerce raw_action (enum or string) into a ProgressAction instance
+    try:
+        action = (
+            raw_action
+            if isinstance(raw_action, ProgressAction)
+            else ProgressAction(str(raw_action))
+        )
+    except Exception:
+        # If we cannot coerce, drop this event from progress handling
+        return None
+
+    # Build target string based on the event type.
+    # Progress display is currently [time] [event] --- [target] [details]
+    namespace = event.namespace
+    agent_name = event_data.get("agent_name")
+
+    target = agent_name
+    details = ""
+    if action == ProgressAction.FATAL_ERROR:
+        details = event_data.get("error_message", "An error occurred")
+    elif "mcp_aggregator" in namespace:
+        server_name = event_data.get("server_name", "")
+        tool_name = event_data.get("tool_name")
+        if tool_name:
+            # fetch(fetch)
+            details = f"{server_name} ({tool_name})"
+        else:
+            details = f"{server_name}"
+
+        # For TOOL_PROGRESS, use progress message if available, otherwise keep default
+        if action == ProgressAction.TOOL_PROGRESS:
+            progress_message = event_data.get("details", "")
+            if progress_message:  # Only override if message is non-empty
+                details = progress_message
+
+    # TODO: there must be a better way :D?!
+    elif "llm" in namespace:
+        model = event_data.get("model", "")
+
+        # For all augmented_llm events, put model info in details column
+        details = f"{model}"
+        chat_turn = event_data.get("chat_turn")
+        if chat_turn is not None:
+            details = f"{model} turn {chat_turn}"
+
+        tool_name = event_data.get("tool_name")
+        tool_event = event_data.get("tool_event")
+        if tool_name:
+            tool_suffix = tool_name
+            if tool_event:
+                tool_suffix = f"{tool_suffix} ({tool_event})"
+            details = f"{details} • {tool_suffix}".strip()
+    else:
+        if not target:
+            target = event_data.get("target", "unknown")
+
+    # Extract streaming token count for STREAMING/THINKING actions
+    streaming_tokens = None
+    if action == ProgressAction.STREAMING or action == ProgressAction.THINKING:
+        streaming_tokens = event_data.get("details", "")
+
+    # Extract progress data for TOOL_PROGRESS actions
+    progress = None
+    total = None
+    if action == ProgressAction.TOOL_PROGRESS:
+        progress = event_data.get("progress")
+        total = event_data.get("total")
+
+    return ProgressEvent(
+        action=action,
+        target=target or "unknown",
+        details=details,
+        agent_name=event_data.get("agent_name"),
+        streaming_tokens=streaming_tokens,
+        progress=progress,
+        total=total,
+    )
+
+
+class EventListener(ABC):
+    """Base async listener that processes events."""
+
+    @abstractmethod
+    async def handle_event(self, event: Event):
+        """Process an incoming event."""
+
+
+class LifecycleAwareListener(EventListener):
+    """
+    Optionally override start()/stop() for setup/teardown.
+    The event bus calls these at bus start/stop time.
+    """
+
+    async def start(self) -> None:
+        """Start an event listener, usually when the event bus is set up."""
+        pass
+
+    async def stop(self) -> None:
+        """Stop an event listener, usually when the event bus is shutting down."""
+        pass
+
+
+class FilteredListener(LifecycleAwareListener):
+    """
+    Only processes events that pass the given filter.
+    Subclasses override _handle_matched_event().
+    """
+
+    def __init__(self, event_filter: EventFilter | None = None) -> None:
+        """
+        Initialize the listener.
+        Args:
+            filter: Event filter to apply to incoming events.
+        """
+        self.filter = event_filter
+
+    async def handle_event(self, event) -> None:
+        if not self.filter or self.filter.matches(event):
+            await self.handle_matched_event(event)
+
+    async def handle_matched_event(self, event: Event) -> None:
+        """Process an event that matches the filter."""
+        pass
+
+
+class LoggingListener(FilteredListener):
+    """
+    Routes events to Python's logging facility with appropriate severity level.
+    """
+
+    def __init__(
+        self,
+        event_filter: EventFilter | None = None,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        """
+        Initialize the listener.
+        Args:
+            logger: Logger to use for event processing. Defaults to 'fast_agent'.
+        """
+        super().__init__(event_filter=event_filter)
+        self.logger = logger or logging.getLogger("fast_agent")
+
+    async def handle_matched_event(self, event) -> None:
+        level_map: dict[EventType, int] = {
+            "debug": logging.DEBUG,
+            "info": logging.INFO,
+            "warning": logging.WARNING,
+            "error": logging.ERROR,
+        }
+        level = level_map.get(event.type, logging.INFO)
+
+        # Check if this is a server stderr message and format accordingly
+        if event.name == "mcpserver.stderr":
+            message = f"MCP Server: {event.message}"
+        else:
+            message = event.message
+
+        self.logger.log(
+            level,
+            "[%s] %s",
+            event.namespace,
+            message,
+            extra={
+                "event_data": event.data,
+                "span_id": event.span_id,
+                "trace_id": event.trace_id,
+                "event_name": event.name,
+            },
+        )
+
+
+class ProgressListener(LifecycleAwareListener):
+    """
+    Listens for all events pre-filtering and converts them to progress events
+    for display. By inheriting directly from LifecycleAwareListener instead of
+    FilteredListener, we get events before any filtering occurs.
+    """
+
+    def __init__(self, display=None) -> None:
+        """Initialize the progress listener.
+        Args:
+            display: Optional display handler. If None, the shared progress_display will be used.
+        """
+        from fast_agent.ui.progress_display import progress_display
+
+        self.display = display or progress_display
+
+    async def start(self) -> None:
+        """Start the progress display."""
+        self.display.start()
+
+    async def stop(self) -> None:
+        """Stop the progress display."""
+        self.display.stop()
+
+    async def handle_event(self, event: Event) -> None:
+        """Process an incoming event and display progress if relevant."""
+
+        if event.data:
+            progress_event = convert_log_event(event)
+            if progress_event:
+                self.display.update(progress_event)
+
+
+class BatchingListener(FilteredListener):
+    """
+    Accumulates events in memory, flushes them in batches.
+    Here we just print the batch size, but you might store or forward them.
+    """
+
+    def __init__(
+        self,
+        event_filter: EventFilter | None = None,
+        batch_size: int = 5,
+        flush_interval: float = 2.0,
+    ) -> None:
+        """
+        Initialize the listener.
+        Args:
+            batch_size: Number of events to accumulate before flushing.
+            flush_interval: Time in seconds to wait before flushing events.
+        """
+        super().__init__(event_filter=event_filter)
+        self.batch_size = batch_size
+        self.flush_interval = flush_interval
+        self.batch: list[Event] = []
+        self.last_flush: float = time.time()  # Time of last flush
+        self._flush_task: asyncio.Task | None = None  # Task for periodic flush loop
+        self._stop_event = None  # Event to signal flush task to stop
+
+    async def start(self, loop=None) -> None:
+        """Spawn a periodic flush loop."""
+        self._stop_event = asyncio.Event()
+        self._flush_task = asyncio.create_task(self._periodic_flush())
+
+    async def stop(self) -> None:
+        """Stop flush loop and flush any remaining events."""
+        if self._stop_event:
+            self._stop_event.set()
+
+        if self._flush_task and not self._flush_task.done():
+            self._flush_task.cancel()
+            await self._flush_task
+            self._flush_task = None
+        await self.flush()
+
+    async def _periodic_flush(self) -> None:
+        try:
+            while not self._stop_event.is_set():
+                try:
+                    await asyncio.wait_for(self._stop_event.wait(), timeout=self.flush_interval)
+                except asyncio.TimeoutError:
+                    await self.flush()
+        # except asyncio.CancelledError:
+        #     break
+        finally:
+            await self.flush()  # Final flush
+
+    async def handle_matched_event(self, event) -> None:
+        self.batch.append(event)
+        if len(self.batch) >= self.batch_size:
+            await self.flush()
+
+    async def flush(self) -> None:
+        """Flush the current batch of events."""
+        if not self.batch:
+            return
+        to_process = self.batch[:]
+        self.batch.clear()
+        self.last_flush = time.time()
+        await self._process_batch(to_process)
+
+    async def _process_batch(self, events: list[Event]) -> None:
+        pass