idun-agent-engine 0.2.7__py3-none-any.whl → 0.3.0__py3-none-any.whl

idun_agent_engine/mcp/registry.py

@@ -0,0 +1,109 @@
+"""Registry for MCP server clients."""
+
+from __future__ import annotations
+
+from typing import Any, cast, TYPE_CHECKING
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_mcp_adapters.sessions import Connection
+
+if TYPE_CHECKING:
+    from google.adk.tools import McpToolset
+    from mcp import StdioServerParameters
+
+try:
+    from google.adk.tools import McpToolset
+    from mcp import StdioServerParameters
+except ImportError:
+    McpToolset = None  # type: ignore
+    StdioServerParameters = None  # type: ignore
+
+from idun_agent_schema.engine.mcp_server import MCPServer
+
+
+class MCPClientRegistry:
+    """Wraps `MultiServerMCPClient` with convenience helpers."""
+
+    def __init__(self, configs: list[MCPServer] | None = None) -> None:
+        self._configs = configs or []
+        self._client: MultiServerMCPClient | None = None
+
+        if self._configs:
+            connections: dict[str, Connection] = {
+                config.name: cast(Connection, config.as_connection_dict())
+                for config in self._configs
+            }
+            self._client = MultiServerMCPClient(connections)
+
+    @property
+    def enabled(self) -> bool:
+        """Return True if at least one MCP server is configured."""
+        return self._client is not None
+
+    @property
+    def client(self) -> MultiServerMCPClient:
+        """Return the underlying MultiServerMCPClient."""
+        if not self._client:
+            raise RuntimeError("No MCP servers configured.")
+        return self._client
+
+    def available_servers(self) -> list[str]:
+        """Return the list of configured MCP server names."""
+        if not self._client:
+            return []
+        return list(self._client.connections.keys())
+
+    def _ensure_server(self, name: str) -> None:
+        if not self._client:
+            raise RuntimeError("MCP client registry is not enabled.")
+        if name not in self._client.connections:
+            available = ", ".join(self._client.connections.keys()) or "none"
+            raise ValueError(
+                f"MCP server '{name}' is not configured. Available: {available}"
+            )
+
+    def get_client(self, name: str | None = None) -> MultiServerMCPClient:
+        """Return the MCP client, optionally ensuring a named server exists."""
+        if name:
+            self._ensure_server(name)
+        return self.client
+
+    def get_session(self, name: str):
+        """Return an async context manager for the given server session."""
+        self._ensure_server(name)
+        return self.client.session(name)
+
+    async def get_tools(self, name: str | None = None) -> list[Any]:
+        """Load tools from all servers or a specific one."""
+        if not self._client:
+            raise RuntimeError("MCP client registry is not enabled.")
+        return await self._client.get_tools(server_name=name)
+
+    def get_adk_toolsets(self) -> list["McpToolset"]:
+        """Return a list of Google ADK McpToolset instances for configured servers."""
+        if McpToolset is None or StdioServerParameters is None:
+            raise ImportError("google-adk and mcp packages are required for ADK toolsets.")
+
+        toolsets = []
+        for config in self._configs:
+            if config.transport == "stdio":
+                if not config.command:
+                    continue
+
+                server_params = StdioServerParameters(
+                    command=config.command,
+                    args=config.args,
+                    env=config.env,
+                    cwd=config.cwd,
+                    encoding=config.encoding or "utf-8",
+                    encoding_error_handler=config.encoding_error_handler or "strict",
+                )
+
+                toolset = McpToolset(
+                    # name=config.name,
+                    connection_params=server_params
+                )
+                toolsets.append(toolset)
+            # TODO: Add support for SSE/HTTP transports when available in ADK/MCP
+
+        return toolsets

idun_agent_engine/observability/__init__.py

@@ -1,13 +1,17 @@
 """Observability package providing provider-agnostic tracing interfaces."""
 
 from .base import (
-    ObservabilityConfig,
+    ObservabilityConfigV1,
+    ObservabilityConfigV2,
     ObservabilityHandlerBase,
     create_observability_handler,
+    create_observability_handlers,
 )
 
 __all__ = [
-    "ObservabilityConfig",
+    "ObservabilityConfigV1",
+    "ObservabilityConfigV2",
     "ObservabilityHandlerBase",
     "create_observability_handler",
+    "create_observability_handlers",
 ]

idun_agent_engine/observability/base.py

@@ -9,7 +9,11 @@ import os
 from abc import ABC, abstractmethod
 from typing import Any
 
-from idun_agent_schema.engine.observability import ObservabilityConfig
+from idun_agent_schema.engine.observability import ObservabilityConfig as ObservabilityConfigV1
+from idun_agent_schema.engine.observability_v2 import (
+    ObservabilityConfig as ObservabilityConfigV2,
+    ObservabilityProvider,
+)
 
 
 class ObservabilityHandlerBase(ABC):
@@ -36,11 +40,24 @@ class ObservabilityHandlerBase(ABC):
 
 
 def _normalize_config(
-    config: ObservabilityConfig | dict[str, Any] | None,
+    config: ObservabilityConfigV1 | ObservabilityConfigV2 | dict[str, Any] | None,
 ) -> dict[str, Any]:
     if config is None:
         return {"enabled": False}
-    if isinstance(config, ObservabilityConfig):
+
+    if isinstance(config, ObservabilityConfigV2):
+        if not config.enabled:
+            return {"enabled": False}
+
+        provider = config.provider.value if hasattr(config.provider, "value") else config.provider
+        options = config.config.model_dump()
+        return {
+            "provider": provider,
+            "enabled": config.enabled,
+            "options": options,
+        }
+
+    if isinstance(config, ObservabilityConfigV1):
         resolved = config.resolved()
         return {
             "provider": resolved.provider,
@@ -55,11 +72,11 @@ def _normalize_config(
 
 
 def create_observability_handler(
-    config: ObservabilityConfig | dict[str, Any] | None,
+    config: ObservabilityConfigV1 | ObservabilityConfigV2 | dict[str, Any] | None,
 ) -> tuple[ObservabilityHandlerBase | None, dict[str, Any] | None]:
     """Factory to create an observability handler based on provider.
 
-    Accepts either an `ObservabilityConfig` or a raw dict.
+    Accepts either an `ObservabilityConfig` (V1 or V2) or a raw dict.
     Returns (handler, info_dict). info_dict can be attached to agent infos for debugging.
     """
     normalized = _normalize_config(config)
@@ -70,18 +87,25 @@ def create_observability_handler(
     if not enabled or not provider:
         return None, {"enabled": False}
 
-    if provider == "langfuse":
+    # Ensure provider is string comparison
+    if hasattr(provider, "value"):
+        provider = provider.value
+
+    # Case-insensitive check for provider
+    provider_upper = str(provider).upper()
+
+    if provider_upper == ObservabilityProvider.LANGFUSE:
         from .langfuse.langfuse_handler import LangfuseHandler
 
         handler = LangfuseHandler(options)
         return handler, {
             "enabled": True,
             "provider": "langfuse",
-            "host": os.getenv("LANGFUSE_HOST"),
+            "host": os.getenv("LANGFUSE_BASE_URL"),
             "run_name": handler.get_run_name(),
         }
 
-    if provider == "phoenix":
+    if provider_upper == ObservabilityProvider.PHOENIX:
         from .phoenix.phoenix_handler import PhoenixHandler
 
         handler = PhoenixHandler(options)
@@ -95,13 +119,31 @@ def create_observability_handler(
             info["project_name"] = project_name
         return handler, info
 
-    if provider == "phoenix-local":
-        from .phoenix_local.phoenix_local_handler import PhoenixLocalHandler
+    # if provider == "phoenix-local":
+    #     from .phoenix_local.phoenix_local_handler import PhoenixLocalHandler
+    #
+    #     handler = PhoenixLocalHandler(options)
+    #     return handler, {
+    #         "enabled": True,
+    #         "provider": "phoenix-local",
+    #     }
 
-        handler = PhoenixLocalHandler(options)
+    if provider_upper == ObservabilityProvider.GCP_LOGGING:
+        from .gcp_logging.gcp_logging_handler import GCPLoggingHandler
+
+        handler = GCPLoggingHandler(options)
         return handler, {
             "enabled": True,
-            "provider": "phoenix-local",
+            "provider": "gcp_logging",
+        }
+
+    if provider_upper == ObservabilityProvider.GCP_TRACE:
+        from .gcp_trace.gcp_trace_handler import GCPTraceHandler
+
+        handler = GCPTraceHandler(options)
+        return handler, {
+            "enabled": True,
+            "provider": "gcp_trace",
         }
 
     return None, {
@@ -109,3 +151,22 @@ def create_observability_handler(
         "provider": provider,
         "error": "Unsupported provider",
     }
+
+def create_observability_handlers(
+    configs: list[ObservabilityConfigV2 | ObservabilityConfigV1] | None,
+) -> tuple[list[ObservabilityHandlerBase], list[dict[str, Any]]]:
+    """Create multiple observability handlers from a list of configs."""
+    handlers = []
+    infos = []
+
+    if not configs:
+        return [], []
+
+    for config in configs:
+        handler, info = create_observability_handler(config)
+        if handler:
+            handlers.append(handler)
+        if info:
+            infos.append(info)
+
+    return handlers, infos

idun_agent_engine/observability/gcp_logging/gcp_logging_handler.py

@@ -0,0 +1,52 @@
+"""GCP Logging observability handler."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..base import ObservabilityHandlerBase
+
+logger = logging.getLogger(__name__)
+
+
+class GCPLoggingHandler(ObservabilityHandlerBase):
+    """GCP Logging handler."""
+
+    provider = "gcp_logging"
+
+    def __init__(self, options: dict[str, Any] | None = None):
+        """Initialize handler."""
+        super().__init__(options)
+        self.options = options or {}
+
+        try:
+            import google.cloud.logging
+        except ImportError as e:
+            logger.error("GCP Logging dependencies not found: %s", e)
+            raise ImportError(
+                "Please install 'google-cloud-logging' to use GCP Logging."
+            ) from e
+
+        project_id = self.options.get("project_id")
+        # If project_id is explicitly provided, use it, otherwise client will auto-detect
+        if project_id:
+            client = google.cloud.logging.Client(project=project_id)
+        else:
+            client = google.cloud.logging.Client()
+
+        # Get logging configuration options
+        log_level = self.options.get("severity", "INFO").upper()
+        level = getattr(logging, log_level, logging.INFO)
+
+        # Setup logging handler
+        # This attaches a CloudLoggingHandler to the root python logger
+        client.setup_logging(log_level=level)
+
+        logger.info("GCP Logging initialized for project: %s", client.project)
+
+    def get_callbacks(self) -> list[Any]:
+        """Return callbacks."""
+        # GCP Logging hooks into the standard python logging module,
+        # so no explicit LangChain callbacks are needed.
+        return []

idun_agent_engine/observability/gcp_trace/gcp_trace_handler.py

@@ -0,0 +1,116 @@
+"""GCP Trace observability handler."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
+
+from ..base import ObservabilityHandlerBase
+
+logger = logging.getLogger(__name__)
+
+
+class GCPTraceHandler(ObservabilityHandlerBase):
+    """GCP Trace handler."""
+
+    provider = "gcp_trace"
+
+    def __init__(self, options: dict[str, Any] | None = None):
+        """Initialize handler."""
+        super().__init__(options)
+        self.options = options or {}
+
+        try:
+            from openinference.instrumentation.langchain import LangChainInstrumentor
+            from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
+        except ImportError as e:
+            logger.error("GCP Trace dependencies not found: %s", e)
+            raise ImportError(
+                "Please install 'opentelemetry-exporter-gcp-trace' and 'openinference-instrumentation-langchain' to use GCP Trace."
+            ) from e
+
+        project_id = self.options.get("project_id")
+        if not project_id:
+            project_id = None
+
+        # Initialize exporter
+        exporter = CloudTraceSpanExporter(
+            project_id=project_id,
+        )
+
+        # Initialize sampler
+        sampling_rate = float(self.options.get("sampling_rate", 1.0))
+        sampler = TraceIdRatioBased(sampling_rate)
+
+        # Initialize resource
+        resource_attributes = {}
+        trace_name = self.options.get("trace_name")
+        if trace_name:
+            resource_attributes["service.name"] = trace_name
+
+        resource = Resource.create(resource_attributes)
+
+        # Initialize tracer provider
+        tracer_provider = TracerProvider(
+            sampler=sampler,
+            resource=resource,
+        )
+
+        # Add span processor
+        flush_interval = int(self.options.get("flush_interval", 5))
+        span_processor = BatchSpanProcessor(
+            exporter, schedule_delay_millis=flush_interval * 1000
+        )
+        tracer_provider.add_span_processor(span_processor)
+
+        # Set global tracer provider
+        trace.set_tracer_provider(tracer_provider)
+
+        # Instrument LangChain with OpenInference
+        LangChainInstrumentor().instrument(tracer_provider=tracer_provider)
+
+        # Instrument Guardrails
+        try:
+            from openinference.instrumentation.guardrails import GuardrailsInstrumentor
+
+            GuardrailsInstrumentor().instrument(tracer_provider=tracer_provider)
+        except ImportError:
+            pass
+
+        # Instrument VertexAI
+        try:
+            from openinference.instrumentation.vertexai import VertexAIInstrumentor
+
+            VertexAIInstrumentor().instrument(tracer_provider=tracer_provider)
+        except ImportError:
+            pass
+
+        # TODO: GCP GoogleADKInstrumentor is n conflist with langfuse, so we don't need to instrument it here
+        # Instrument Google ADK
+        # try:
+        #     from openinference.instrumentation.google_adk import GoogleADKInstrumentor
+
+        #     GoogleADKInstrumentor().instrument(tracer_provider=tracer_provider)
+        # except ImportError:
+        #     pass
+
+        # Instrument MCP
+        try:
+            from openinference.instrumentation.mcp import MCPInstrumentor
+
+            MCPInstrumentor().instrument(tracer_provider=tracer_provider)
+        except ImportError:
+            pass
+
+        logger.info("GCP Trace initialized for project: %s", project_id or "auto-detected")
+
+    def get_callbacks(self) -> list[Any]:
+        """Return callbacks."""
+        # OpenTelemetry instrumentation uses global tracer provider, so no explicit callbacks needed here
+        return []

idun_agent_engine/observability/langfuse/langfuse_handler.py

@@ -21,7 +21,7 @@ class LangfuseHandler(ObservabilityHandlerBase):
         opts = self.options
 
         # Resolve and set env vars as required by Langfuse
-        host = self._resolve_env(opts.get("host")) or os.getenv("LANGFUSE_HOST")
+        host = self._resolve_env(opts.get("host")) or os.getenv("LANGFUSE_BASE_URL")
         public_key = self._resolve_env(opts.get("public_key")) or os.getenv(
             "LANGFUSE_PUBLIC_KEY"
         )
@@ -30,7 +30,7 @@ class LangfuseHandler(ObservabilityHandlerBase):
         )
 
         if host:
-            os.environ["LANGFUSE_HOST"] = host
+            os.environ["LANGFUSE_BASE_URL"] = host
         if public_key:
             os.environ["LANGFUSE_PUBLIC_KEY"] = public_key
         if secret_key:
@@ -40,10 +40,11 @@ class LangfuseHandler(ObservabilityHandlerBase):
         self._callbacks: list[Any] = []
         self._langfuse_client = None
         try:
-            from langfuse.callback import CallbackHandler
-            from langfuse.client import Langfuse
+            from langfuse import get_client
+            from langfuse.langchain import CallbackHandler
 
-            self._langfuse_client = Langfuse()
+            # Initialize client for auth check
+            self._langfuse_client = get_client()
 
             try:
                 if self._langfuse_client.auth_check():
@@ -52,11 +53,17 @@ class LangfuseHandler(ObservabilityHandlerBase):
                     print(
                         "Authentication failed. Please check your credentials and host."
                     )
-            except Exception:
-                pass
-
-            self._callbacks = [CallbackHandler()]
-        except Exception:
+            except Exception as e:
+                print(f"Error during Langfuse client authentication: {e}")
+
+            # Initialize callback handler
+            # We pass the resolved credentials explicitly to ensure they are used
+            # even if env vars were not successfully set or read.
+            self._callbacks = [
+                CallbackHandler()
+            ]
+        except Exception as e:
+            print(f"Failed to initialize Langfuse callback/client: {e}")
             self._callbacks = []
 
     @staticmethod

idun_agent_engine/server/dependencies.py

@@ -1,8 +1,9 @@
 """Dependency injection helpers for FastAPI routes."""
 
-from fastapi import Request
+from fastapi import HTTPException, Request, status
 
 from ..core.config_builder import ConfigBuilder
+from ..mcp import MCPClientRegistry
 
 
 async def get_agent(request: Request):
@@ -38,3 +39,14 @@ async def get_copilotkit_agent(request: Request):
         app_config = ConfigBuilder.load_from_file()
         copilotkit_agent = await ConfigBuilder.initialize_agent_from_config(app_config)
         return copilotkit_agent
+
+
+def get_mcp_registry(request: Request) -> MCPClientRegistry:
+    """Return the configured MCP registry if available."""
+    registry: MCPClientRegistry | None = getattr(request.app.state, "mcp_registry", None)
+    if registry is None or not registry.enabled:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="MCP servers are not configured for this engine.",
+        )
+    return registry

idun_agent_engine/server/lifespan.py

@@ -4,34 +4,34 @@ Initializes the agent at startup and cleans up resources on shutdown.
 """
 
 import inspect
+from collections.abc import Sequence
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
 
 from ..core.config_builder import ConfigBuilder
+from ..mcp import MCPClientRegistry
 
+from idun_agent_schema.engine.guardrails import Guardrails, Guardrail
 
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """FastAPI lifespan context to initialize and teardown the agent."""
-    # Load config and initialize agent on startup
-    print("Server starting up...")
-    engine_config = app.state.engine_config
+from ..guardrails.base import BaseGuardrail
 
-    # Use ConfigBuilder's centralized agent initialization
-    agent_instance = await ConfigBuilder.initialize_agent_from_config(engine_config)
 
-    # Store both in app state
-    app.state.agent = agent_instance
-    app.state.config = engine_config
+def _parse_guardrails(guardrails_obj: Guardrails) -> Sequence[BaseGuardrail]:
+    """Adds the position of the guardrails (input/output) and returns the lift of updated guardrails."""
 
-    agent_name = getattr(agent_instance, "name", "Unknown")
-    print(f"✅ Agent '{agent_name}' initialized and ready to serve!")
+    from ..guardrails.guardrails_hub.guardrails_hub import GuardrailsHubGuard as GHGuard
 
-    yield
+    if not guardrails_obj.enabled:
+        return []
 
-    # Clean up on shutdown
-    print("🔄 Idun Agent Engine shutting down...")
+    return [GHGuard(guard, position="input") for guard in guardrails_obj.input] + [
+        GHGuard(guard, position="output") for guard in guardrails_obj.output
+    ]
+
+
+async def cleanup_agent(app: FastAPI):
+    """Clean up agent resources."""
     agent = getattr(app.state, "agent", None)
     if agent is not None:
         close_fn = getattr(agent, "close", None)
@@ -39,4 +39,71 @@ async def lifespan(app: FastAPI):
             result = close_fn()
             if inspect.isawaitable(result):
                 await result
+
+
+async def configure_app(app: FastAPI, engine_config):
+    """Initialize the agent, MCP registry, guardrails, and app state with the given engine config."""
+    guardrails_obj = engine_config.guardrails
+    guardrails = _parse_guardrails(guardrails_obj) if guardrails_obj else []
+
+    print("guardrails: ", guardrails)
+
+    # # Initialize MCP Registry first
+    # mcp_registry = MCPClientRegistry(engine_config.mcp_servers)
+    # app.state.mcp_registry = mcp_registry
+
+    # Use ConfigBuilder's centralized agent initialization, passing the registry
+    try:
+        agent_instance = await ConfigBuilder.initialize_agent_from_config(
+            engine_config
+        )
+    except Exception as e:
+        raise ValueError(
+            f"Error retrieving agent instance from ConfigBuilder: {e}"
+        ) from e
+
+    app.state.agent = agent_instance
+    app.state.config = engine_config
+    app.state.engine_config = engine_config
+
+    app.state.guardrails = guardrails  # TODO: to reactivate
+    agent_name = getattr(agent_instance, "name", "Unknown")
+    print(f"✅ Agent '{agent_name}' initialized and ready to serve!")
+
+    # Setup AGUI routes if the agent is a LangGraph agent
+    from ..agent.langgraph.langgraph import LanggraphAgent
+    from ..agent.adk.adk import AdkAgent
+    # from ..server.routers.agui import setup_agui_router
+
+    if isinstance(agent_instance, (LanggraphAgent, AdkAgent)):
+        try:
+            # compiled_graph = getattr(agent_instance, "agent_instance")
+            # app.state.copilotkit_agent = setup_agui_router(app, agent_instance) # TODO: agent_instance is a compiled graph (duplicate agent_instance name not clear)
+            app.state.copilotkit_agent = agent_instance.copilotkit_agent_instance
+        except Exception as e:
+            print(f"⚠️ Warning: Failed to setup AGUI routes: {e}")
+            # Continue even if AGUI setup fails
+
+    # if app.state.mcp_registry.enabled:
+    #     servers = ", ".join(app.state.mcp_registry.available_servers())
+    #     print(f"🔌 MCP servers ready: {servers}")
+
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """FastAPI lifespan context to initialize and teardown the agent."""
+
+    # Load config and initialize agent on startup
+    print("Server starting up...")
+    if not app.state.engine_config:
+        raise ValueError("Error: No Engine configuration found.")
+
+    await configure_app(app, app.state.engine_config)
+
+    yield
+
+    # Clean up on shutdown
+    print("🔄 Idun Agent Engine shutting down...")
+    await cleanup_agent(app)
     print("✅ Agent resources cleaned up successfully.")