idun-agent-engine 0.3.4__py3-none-any.whl

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/__init__.py

@@ -0,0 +1,5 @@
+"""Langfuse observability integration package."""
+
+from .langfuse_handler import LangfuseHandler
+
+__all__ = ["LangfuseHandler"]

idun_agent_engine/observability/langfuse/langfuse_handler.py

@@ -0,0 +1,79 @@
+"""Langfuse observability handler implementation."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from idun_agent_schema.engine.observability import _resolve_env
+
+from ..base import ObservabilityHandlerBase
+
+
+class LangfuseHandler(ObservabilityHandlerBase):
+    """Langfuse handler providing LangChain callbacks and client setup."""
+
+    provider = "langfuse"
+
+    def __init__(self, options: dict[str, Any] | None = None):
+        """Initialize handler, resolving env and preparing callbacks."""
+        super().__init__(options)
+        opts = self.options
+
+        # Resolve and set env vars as required by Langfuse
+        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"
+        )
+        secret_key = self._resolve_env(opts.get("secret_key")) or os.getenv(
+            "LANGFUSE_SECRET_KEY"
+        )
+
+        if host:
+            os.environ["LANGFUSE_BASE_URL"] = host
+        if public_key:
+            os.environ["LANGFUSE_PUBLIC_KEY"] = public_key
+        if secret_key:
+            os.environ["LANGFUSE_SECRET_KEY"] = secret_key
+
+        # Instantiate callback handler lazily to avoid hard dep if not installed
+        self._callbacks: list[Any] = []
+        self._langfuse_client = None
+        try:
+            from langfuse import get_client
+            from langfuse.langchain import CallbackHandler
+
+            # Initialize client for auth check
+            self._langfuse_client = get_client()
+
+            try:
+                if self._langfuse_client.auth_check():
+                    print("Langfuse client is authenticated and ready!")
+                else:
+                    print(
+                        "Authentication failed. Please check your credentials and host."
+                    )
+            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
+    def _resolve_env(value: str | None) -> str | None:
+        return _resolve_env(value)
+
+    def get_callbacks(self) -> list[Any]:
+        """Return LangChain-compatible callback handlers (if available)."""
+        return self._callbacks
+
+    def get_client(self):
+        """Return underlying Langfuse client instance (if created)."""
+        return self._langfuse_client

idun_agent_engine/observability/phoenix/__init__.py

@@ -0,0 +1,5 @@
+"""Arize Phoenix observability integration package."""
+
+from .phoenix_handler import PhoenixHandler
+
+__all__ = ["PhoenixHandler"]

idun_agent_engine/observability/phoenix/phoenix_handler.py

@@ -0,0 +1,65 @@
+"""Phoenix observability handler implementation."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from idun_agent_schema.engine.observability import _resolve_env
+
+from ..base import ObservabilityHandlerBase
+
+
+class PhoenixHandler(ObservabilityHandlerBase):
+    """Phoenix handler configuring OpenTelemetry and LangChain instrumentation."""
+
+    provider = "phoenix"
+
+    def __init__(self, options: dict[str, Any] | None = None):
+        """Initialize handler, resolving env and setting up instrumentation."""
+        super().__init__(options)
+        opts = self.options
+
+        # Resolve and set env vars as required by Phoenix
+        api_key = self._resolve_env(opts.get("api_key")) or os.getenv("PHOENIX_API_KEY")
+        collector = (
+            self._resolve_env(opts.get("collector"))
+            or self._resolve_env(opts.get("collector_endpoint"))
+            or os.getenv("PHOENIX_COLLECTOR_ENDPOINT")
+        )
+        self.project_name: str = opts.get("project_name") or "default"
+
+        if api_key:
+            os.environ["PHOENIX_API_KEY"] = api_key
+        if collector:
+            os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = collector
+
+        # Some older Phoenix deployments (before 2025-06-24) require setting client headers.
+        # If not explicitly provided, set it from API key when available for backward compatibility.
+        client_headers = opts.get("client_headers")
+        if isinstance(client_headers, str) and client_headers:
+            os.environ["PHOENIX_CLIENT_HEADERS"] = client_headers
+        elif api_key and not os.getenv("PHOENIX_CLIENT_HEADERS"):
+            os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={api_key}"
+
+        # Configure tracer provider using phoenix.otel.register
+        self._callbacks: list[Any] = []
+        try:
+            from openinference.instrumentation.langchain import LangChainInstrumentor
+            from phoenix.otel import register  # type: ignore
+
+            tracer_provider = register(
+                project_name=self.project_name, auto_instrument=True
+            )
+            LangChainInstrumentor().instrument(tracer_provider=tracer_provider)
+        except Exception:
+            # Silent failure; user may not have phoenix installed
+            pass
+
+    @staticmethod
+    def _resolve_env(value: str | None) -> str | None:
+        return _resolve_env(value)
+
+    def get_callbacks(self) -> list[Any]:
+        """Return callbacks (Phoenix instruments globally; this may be empty)."""
+        return self._callbacks

idun_agent_engine/observability/phoenix_local/__init__.py

@@ -0,0 +1,5 @@
+"""Arize Phoenix observability integration package."""
+
+from .phoenix_local_handler import PhoenixLocalHandler
+
+__all__ = ["PhoenixLocalHandler"]

idun_agent_engine/observability/phoenix_local/phoenix_local_handler.py

@@ -0,0 +1,123 @@
+"""Phoenix observability handler implementation."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import subprocess
+from typing import Any
+
+from idun_agent_schema.engine.observability import _resolve_env
+
+from ..base import ObservabilityHandlerBase
+
+logger = logging.getLogger(__name__)
+
+
+class PhoenixLocalHandler(ObservabilityHandlerBase):
+    """Phoenix handler configuring OpenTelemetry and LangChain instrumentation."""
+
+    provider = "phoenix-local"
+
+    def __init__(
+        self,
+        options: dict[str, Any] | None = None,
+        default_endpoint: str = "http://0.0.0.0:6006",
+    ):
+        """Initialize handler, start Phoenix via CLI, and set up instrumentation.
+
+        Args:
+            options: Configuration options dictionary
+            default_endpoint: Default Phoenix collector endpoint URL
+        """
+        logger.info("Initializing PhoenixLocalHandler")
+
+        super().__init__(options)
+        opts = self.options or {}
+
+        # Initialize instance variables
+        self._callbacks: list[Any] = []
+        self._proc: subprocess.Popen[bytes] | None = None
+        self.default_endpoint = default_endpoint
+        self.project_name: str = "default"
+
+        self._configure_collector_endpoint(opts)
+        self._start_phoenix_cli()
+
+        try:
+            from openinference.instrumentation.langchain import LangChainInstrumentor
+            from phoenix.otel import register
+
+            logger.debug("Successfully imported Phoenix dependencies")
+
+            self.project_name = opts.get("project_name") or "default"
+            logger.info(f"Using project name: {self.project_name}")
+
+            tracer_provider = register(
+                project_name=self.project_name, auto_instrument=True
+            )
+
+            LangChainInstrumentor().instrument(tracer_provider=tracer_provider)
+
+        except ImportError as e:
+            logger.error(f"Missing required Phoenix dependencies: {e}")
+            raise ImportError(f"Phoenix dependencies not found: {e}. ") from e
+
+        except Exception as e:
+            logger.error(f"Failed to set up Phoenix instrumentation: {e}")
+            raise RuntimeError(f"Phoenix instrumentation setup failed: {e}") from e
+
+        logger.info("Phoenix local handler initialized...")
+
+    def _configure_collector_endpoint(self, opts: dict[str, Any]) -> None:
+        """Configure the Phoenix collector endpoint from various sources."""
+        logger.debug("Configuring collector endpoint")
+
+        collector = (
+            self._resolve_env(opts.get("collector"))
+            or self._resolve_env(opts.get("collector_endpoint"))
+            or os.getenv("PHOENIX_COLLECTOR_ENDPOINT")
+            or self.default_endpoint
+        )
+
+        logger.info(f"Setting Phoenix collector endpoint to: {collector}")
+        os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = collector
+        self.collector_endpoint = collector
+
+    def _start_phoenix_cli(self) -> None:
+        """Start pheonix subprocess."""
+        try:
+            cmd = "phoenix serve"
+            logger.debug(f"Executing command: {cmd}")
+
+            self._proc = subprocess.Popen(
+                shlex.split(cmd),
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True,
+            )
+
+            logger.info(f"Phoenix server started with PID: {self._proc.pid}")
+
+        except FileNotFoundError as e:
+            logger.error(f"Phoenix CLI not found. Make sure Phoenix is installed : {e}")
+            self._proc = None
+
+        except subprocess.SubprocessError as e:
+            logger.error(f"Failed to start Phoenix CLI subprocess: {e}")
+            self._proc = None
+
+        except Exception as e:
+            logger.error(f"Unexpected error starting Phoenix CLI: {e}")
+            self._proc = None
+
+    @staticmethod
+    def _resolve_env(value: str | None) -> str | None:
+        """Resolve environment variable value."""
+        return _resolve_env(value)
+
+    def get_callbacks(self) -> list[Any]:
+        """Return callbacks (Phoenix instruments globally; this may be empty)."""
+        logger.debug("Getting callbacks (Phoenix uses global instrumentation)")
+        return self._callbacks

idun_agent_engine/server/__init__.py

@@ -0,0 +1,5 @@
+"""Server package for FastAPI app components and configuration."""
+
+from . import dependencies, lifespan, server_config
+
+__all__ = ["server_config", "dependencies", "lifespan"]

idun_agent_engine/server/dependencies.py

@@ -0,0 +1,52 @@
+"""Dependency injection helpers for FastAPI routes."""
+
+from fastapi import HTTPException, Request, status
+
+from ..core.config_builder import ConfigBuilder
+from ..mcp import MCPClientRegistry
+
+
+async def get_agent(request: Request):
+    """Return the pre-initialized agent instance from the app state.
+
+    Falls back to loading from the default config if not present (e.g., tests).
+    """
+    if hasattr(request.app.state, "agent"):
+        return request.app.state.agent
+    else:
+        # This is a fallback for cases where the lifespan event did not run,
+        # like in some testing scenarios.
+        # Consider logging a warning here.
+        print("⚠️  Agent not found in app state, initializing fallback agent...")
+
+        app_config = ConfigBuilder.load_from_file()
+        agent = await ConfigBuilder.initialize_agent_from_config(app_config)
+        return agent
+
+async def get_copilotkit_agent(request: Request):
+    """Return the pre-initialized agent instance from the app state.
+
+    Falls back to loading from the default config if not present (e.g., tests).
+    """
+    if hasattr(request.app.state, "copilotkit_agent"):
+        return request.app.state.copilotkit_agent
+    else:
+        # This is a fallback for cases where the lifespan event did not run,
+        # like in some testing scenarios.
+        # Consider logging a warning here.
+        print("⚠️  CopilotKit agent not found in app state, initializing fallback agent...")
+
+        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

@@ -0,0 +1,106 @@
+"""Server lifespan management utilities.
+
+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
+
+from ..guardrails.base import BaseGuardrail
+
+
+def _parse_guardrails(guardrails_obj: Guardrails) -> Sequence[BaseGuardrail]:
+    """Adds the position of the guardrails (input/output) and returns the lift of updated guardrails."""
+
+    from ..guardrails.guardrails_hub.guardrails_hub import GuardrailsHubGuard as GHGuard
+
+    if not guardrails_obj.enabled:
+        return []
+
+    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)
+        if callable(close_fn):
+            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
+    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.")

idun_agent_engine/server/routers/__init__.py

@@ -0,0 +1,5 @@
+"""FastAPI routers for the engine service."""
+
+from . import agent, base
+
+__all__ = ["agent", "base"]