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

idun_agent_engine/core/server_runner.py

@@ -0,0 +1,145 @@
+"""Server Runner for Idun Agent Engine.
+
+This module provides convenient functions to run FastAPI applications created with
+the Idun Agent Engine. It handles common deployment scenarios and provides sensible defaults.
+"""
+
+import uvicorn
+from fastapi import FastAPI
+
+
+def run_server(
+    app: FastAPI,
+    host: str = "0.0.0.0",
+    port: int = 8000,
+    reload: bool = False,
+    log_level: str = "info",
+    workers: int | None = None,
+) -> None:
+    """Run a FastAPI application created with Idun Agent Engine.
+
+    This is a convenience function that wraps uvicorn.run() with sensible defaults
+    for serving agent applications. It automatically handles common deployment scenarios.
+
+    Args:
+        app: The FastAPI application created with create_app()
+        host: Host to bind the server to. Defaults to "0.0.0.0" (all interfaces)
+        port: Port to bind the server to. Defaults to 8000
+        reload: Enable auto-reload for development. Defaults to False
+        log_level: Logging level. Defaults to "info"
+        workers: Number of worker processes. If None, uses single process
+
+    Example:
+        from idun_agent_engine import create_app, run_server
+
+        # Create your app
+        app = create_app("config.yaml")
+
+        # Run in development mode
+        run_server(app, reload=True)
+
+        # Run in production mode
+        run_server(app, workers=4)
+    """
+    print(f"🌐 Starting Idun Agent Engine server on http://{host}:{port}...")
+    print(f"📚 API documentation available at http://{host}:{port}/docs")
+
+    if reload and workers:
+        print(
+            "⚠️  Warning: reload=True is incompatible with workers > 1. Disabling reload."
+        )
+        reload = False
+
+    print("Config: ", app.state.engine_config)
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        log_level=log_level,
+    )
+
+
+def run_server_from_config(config_path: str = "config.yaml", **kwargs) -> None:
+    """Create and run a server directly from a configuration file.
+
+    This is the most convenient way to start a server - it combines create_app()
+    and run_server() in a single function call using ConfigBuilder.
+
+    Args:
+        config_path: Path to the configuration YAML file
+        **kwargs: Additional arguments passed to run_server()
+
+    Example:
+        # Run server directly from config
+        run_server_from_config("my_agent.yaml", port=8080, reload=True)
+    """
+    from .app_factory import create_app
+    from .config_builder import ConfigBuilder
+
+    # Load configuration using ConfigBuilder
+    engine_config = ConfigBuilder.load_from_file(config_path)
+
+    # Create app with the loaded config
+    app = create_app(engine_config=engine_config)
+
+    # Extract port from config if not overridden
+    if "port" not in kwargs:
+        kwargs["port"] = engine_config.server.api.port
+
+    # Show configuration info
+    print(f"🔧 Loaded configuration from {config_path}")
+    # Best-effort: handle both dict-like and model access
+    agent_name = (
+        engine_config.agent.config.get("name")  # type: ignore[call-arg, index]
+        if hasattr(engine_config.agent.config, "get")
+        else getattr(engine_config.agent.config, "name", "Unknown")
+    )
+    print(f"🤖 Agent: {agent_name} ({engine_config.agent.type})")
+
+    run_server(app, **kwargs)
+
+
+def run_server_from_builder(config_builder, **kwargs) -> None:
+    """Create and run a server directly from a ConfigBuilder instance.
+
+    This allows for programmatic configuration with immediate server startup.
+
+    Args:
+        config_builder: ConfigBuilder instance (can be built or unbuilt)
+        **kwargs: Additional arguments passed to run_server()
+
+    Example:
+        from idun_agent_engine import ConfigBuilder
+
+        builder = (ConfigBuilder()
+                  .with_langgraph_agent(name="My Agent", graph_definition="agent.py:graph")
+                  .with_api_port(8080))
+
+        run_server_from_builder(builder, reload=True)
+    """
+    from .app_factory import create_app
+
+    # Build the configuration if it's a ConfigBuilder instance
+    if hasattr(config_builder, "build"):
+        engine_config = config_builder.build()
+    else:
+        # Assume it's already an EngineConfig
+        engine_config = config_builder
+
+    # Create app with the config
+    app = create_app(engine_config=engine_config)
+
+    # Extract port from config if not overridden
+    if "port" not in kwargs:
+        kwargs["port"] = engine_config.server.api.port
+
+    # Show configuration info
+    print("🔧 Using programmatic configuration")
+    agent_name = (
+        engine_config.agent.config.get("name")  # type: ignore[call-arg, index]
+        if hasattr(engine_config.agent.config, "get")
+        else getattr(engine_config.agent.config, "name", "Unknown")
+    )
+    print(f"🤖 Agent: {agent_name} ({engine_config.agent.type})")
+
+    run_server(app, **kwargs)

idun_agent_engine/guardrails/base.py

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from idun_agent_schema.engine.guardrails import Guardrail
+
+
+class BaseGuardrail(ABC):
+    """Base class for different guardrail providers."""
+
+    # TODO: output
+
+    def __init__(self, config: Guardrail) -> None:
+        if not isinstance(config, Guardrail):
+            raise TypeError(
+                f"The Guardrail must be a `Guardrail` schema type, received instead: {type(config)}"
+            )
+        self._guardrail_config = config
+        # config for the specific guardrails type. currently, can only be guardrails_hub config
+        self._instance_config: dict[str, Any] = None
+
+    @abstractmethod
+    def validate(self, input: str) -> bool:
+        """Used for validating user input, or LLM output."""
+        pass

idun_agent_engine/guardrails/guardrails_hub/guardrails_hub.py

@@ -0,0 +1,101 @@
+"""Guardrails."""
+
+from guardrails import Guard
+from idun_agent_schema.engine.guardrails import Guardrail as GuardrailSchema
+from idun_agent_schema.engine.guardrails_type import (
+    GuardrailType,
+)
+
+from ..base import BaseGuardrail
+
+
+def get_guard_instance(name: str) -> Guard:
+    """Returns a map of guard type -> guard instance."""
+    if name == "BAN_LIST":
+        from guardrails.hub import BanList
+
+        return BanList
+
+    elif name == "NSFW":
+        from guardrails.hub import NSFWText
+
+        return NSFWText
+
+    elif name == "COMPETITOR_CHECK":
+        from guardrails.hub import CompetitorCheck
+
+        return CompetitorCheck
+
+    else:
+        raise ValueError(f"Guard {name} not found.")
+
+
+class GuardrailsHubGuard(BaseGuardrail):
+    """Class for managing guardrails from `guardrailsai`'s hub."""
+
+    def __init__(self, config: GuardrailSchema, position: str) -> None:
+        super().__init__(config)
+
+        self._guard_type = self._guardrail_config.type
+        self._guard_config = self._guardrail_config.config
+
+        if self._guard_type == GuardrailType.GUARDRAILS_HUB:
+            self._guard_url = self._guardrail_config.config["guard_url"]
+
+        self.reject_message: str = self._guard_config["reject_message"]
+        self._install_model()
+        self._guard: Guard | None = self.setup_guard()
+        self.position: str = position
+
+    def _install_model(self) -> None:
+        import subprocess
+
+        from guardrails import install
+
+        try:
+            api_key = self._guardrail_config.config["api_key"]
+            subprocess.run(
+                [
+                    "guardrails",
+                    "configure",
+                    "--token",
+                    api_key,
+                    "--disable-remote-inferencing",  # TODO: maybe provide this as feat
+                    "--disable-metrics",
+                ],
+                check=True,
+            )
+            print(f"Installing model: {self._guard_url}..")
+            install(self._guard_url, quiet=True, install_local_models=True)
+        except Exception as e:
+            raise OSError(f"Cannot install model {self._guard_url}: {e}") from e
+
+    def setup_guard(self) -> Guard | None:
+        """Installs and configures the guard based on its yaml config."""
+        if self._guard_type == GuardrailType.GUARDRAILS_HUB:
+            self._install_model()
+            guard_name = self._guardrail_config.config.get("guard")
+            guard = get_guard_instance(guard_name)
+            if guard is None:
+                raise ValueError(
+                    f"Guard: {self.guard_type} is not yet supported, or does not exist."
+                )
+
+            guard_instance_params = self._guardrail_config.config.get(
+                "guard_config", {}
+            )
+            guard_instance = guard(**guard_instance_params)
+            for param, value in self._guardrail_config.config["guard_config"].items():
+                setattr(guard, param, value)
+            return guard_instance
+        elif self._guard_type == GuardrailType.CUSTOM_LLM:
+            raise NotImplementedError("Support for CUSTOM_LLM not yet provided.")
+
+    def validate(self, input: str) -> bool:
+        """TODO."""
+        main_guard = Guard().use(self._guard)
+        try:
+            main_guard.validate(input)
+            return True
+        except Exception:
+            return False

idun_agent_engine/guardrails/guardrails_hub/utils.py

@@ -0,0 +1 @@
+"""Utils module."""

idun_agent_engine/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP utilities for Idun Agent Engine."""
+
+from .registry import MCPClientRegistry
+from .helpers import get_adk_tools_from_api, get_adk_tools_from_file
+__all__ = ["MCPClientRegistry", "get_adk_tools_from_api", "get_adk_tools_from_file", "get_adk_tools"]

idun_agent_engine/mcp/helpers.py

@@ -0,0 +1,97 @@
+from pathlib import Path
+from typing import Any
+import yaml
+import requests
+import os
+from idun_agent_engine.mcp.registry import MCPClientRegistry
+from idun_agent_schema.engine.mcp_server import MCPServer
+
+def _get_toolsets_from_data(config_data: dict[str, Any]) -> list[Any]:
+    """Internal helper to extract toolsets from config dictionary."""
+    # Handle both snake_case and camelCase for mcp_servers
+    # Note: logic in ConfigBuilder suggests looking inside 'engine_config' if present,
+    # but this helper expects the dictionary containing 'mcp_servers' directly
+    # or performs the search itself.
+
+    mcp_configs_data = config_data.get("mcp_servers") or config_data.get("mcpServers")
+
+    if not mcp_configs_data:
+        return []
+
+    mcp_configs = [MCPServer.model_validate(c) for c in mcp_configs_data]
+    registry = MCPClientRegistry(mcp_configs)
+
+    try:
+        return registry.get_adk_toolsets()
+    except ImportError:
+        raise
+
+def get_adk_tools_from_file(config_path: str | Path) -> list[Any]:
+    """
+    Loads MCP configurations from a YAML file and returns a list of ADK toolsets.
+
+    Args:
+        config_path: Path to the configuration YAML file.
+
+    Returns:
+        List of initialized ADK McpToolset instances.
+    """
+    path = Path(config_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Configuration file not found at {path}")
+
+    with open(path) as f:
+        config_data = yaml.safe_load(f)
+
+    # Check if wrapped in engine_config (common pattern in idun)
+    if "engine_config" in config_data:
+        config_data = config_data["engine_config"]
+
+    return _get_toolsets_from_data(config_data)
+
+def get_adk_tools_from_api() -> list[Any]:
+    """
+    Fetches configuration from the Idun Manager API and returns a list of ADK toolsets.
+
+    Args:
+        agent_api_key: The API key for authentication.
+        manager_url: The base URL of the Idun Manager (e.g. http://localhost:8000).
+
+    Returns:
+        List of initialized ADK McpToolset instances.
+    """
+    api_key = os.environ.get("IDUN_AGENT_API_KEY")
+    manager_host = os.environ.get("IDUN_MANAGER_HOST")
+    headers = {"auth": f"Bearer {api_key}"}
+    url = f"{manager_host.rstrip('/')}/api/v1/agents/config"
+
+    try:
+        response = requests.get(url=url, headers=headers)
+        response.raise_for_status()
+
+        config_data = yaml.safe_load(response.text)
+
+        # Config from API is typically wrapped in engine_config
+        if "engine_config" in config_data:
+            config_data = config_data["engine_config"]
+
+        return _get_toolsets_from_data(config_data)
+
+    except requests.RequestException as e:
+        raise ValueError(f"Failed to fetch config from API: {e}") from e
+    except yaml.YAMLError as e:
+        raise ValueError(f"Failed to parse config YAML: {e}") from e
+
+
+def get_adk_tools() -> list[Any]:
+    """
+    Fetches configuration from the Idun Manager API and returns a list of ADK toolsets.
+
+    Args:
+        agent_api_key: The API key for authentication.
+        manager_url: The base URL of the Idun Manager (e.g. http://localhost:8000).
+
+    Returns:
+        List of initialized ADK McpToolset instances.
+    """
+    return get_adk_tools_from_api()

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

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

idun_agent_engine/observability/base.py

@@ -0,0 +1,172 @@
+"""Observability base classes and factory functions.
+
+Defines the provider-agnostic interface and a factory to create handlers.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from typing import Any
+
+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):
+    """Abstract base class for observability handlers.
+
+    Concrete implementations must provide provider name and callbacks.
+    """
+
+    provider: str
+
+    def __init__(self, options: dict[str, Any] | None = None) -> None:
+        """Initialize handler with provider-specific options."""
+        self.options: dict[str, Any] = options or {}
+
+    @abstractmethod
+    def get_callbacks(self) -> list[Any]:
+        """Return a list of callbacks (can be empty)."""
+        raise NotImplementedError
+
+    def get_run_name(self) -> str | None:
+        """Optional run name used by frameworks that support it."""
+        run_name = self.options.get("run_name")
+        return run_name if isinstance(run_name, str) else None
+
+
+def _normalize_config(
+    config: ObservabilityConfigV1 | ObservabilityConfigV2 | dict[str, Any] | None,
+) -> dict[str, Any]:
+    if config is None:
+        return {"enabled": False}
+
+    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,
+            "enabled": resolved.enabled,
+            "options": resolved.options,
+        }
+    # Assume dict-like
+    provider = (config or {}).get("provider")
+    enabled = bool((config or {}).get("enabled", False))
+    options = dict((config or {}).get("options", {}))
+    return {"provider": provider, "enabled": enabled, "options": options}
+
+
+def create_observability_handler(
+    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` (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)
+    provider = normalized.get("provider")
+    enabled = normalized.get("enabled", False)
+    options: dict[str, Any] = normalized.get("options", {})
+
+    if not enabled or not provider:
+        return None, {"enabled": False}
+
+    # 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_BASE_URL"),
+            "run_name": handler.get_run_name(),
+        }
+
+    if provider_upper == ObservabilityProvider.PHOENIX:
+        from .phoenix.phoenix_handler import PhoenixHandler
+
+        handler = PhoenixHandler(options)
+        info: dict[str, Any] = {
+            "enabled": True,
+            "provider": "phoenix",
+            "collector": os.getenv("PHOENIX_COLLECTOR_ENDPOINT"),
+        }
+        project_name = getattr(handler, "project_name", None)
+        if project_name:
+            info["project_name"] = project_name
+        return handler, info
+
+    # if provider == "phoenix-local":
+    #     from .phoenix_local.phoenix_local_handler import PhoenixLocalHandler
+    #
+    #     handler = PhoenixLocalHandler(options)
+    #     return handler, {
+    #         "enabled": True,
+    #         "provider": "phoenix-local",
+    #     }
+
+    if provider_upper == ObservabilityProvider.GCP_LOGGING:
+        from .gcp_logging.gcp_logging_handler import GCPLoggingHandler
+
+        handler = GCPLoggingHandler(options)
+        return handler, {
+            "enabled": True,
+            "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, {
+        "enabled": False,
+        "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