idun-agent-engine 0.3.9__py3-none-any.whl → 0.4.1__py3-none-any.whl

idun_agent_engine/_version.py

@@ -1,3 +1,3 @@
 """Version information for Idun Agent Engine."""
 
-__version__ = "0.3.9"
+__version__ = "0.4.1"

idun_agent_engine/agent/adk/adk.py

@@ -123,7 +123,7 @@ class AdkAgent(agent_base.BaseAgent):
         # Observability (provider-agnostic)
         if observability_config:
             handlers, infos = observability.create_observability_handlers(
-                observability_config # type: ignore[arg-type]
+                observability_config  # type: ignore[arg-type]
             )
             self._obs_callbacks = []
             for handler in handlers:
@@ -153,6 +153,7 @@ class AdkAgent(agent_base.BaseAgent):
 
                 if is_langfuse_enabled:
                     import os
+
                     langfuse_pk = os.environ.get("LANGFUSE_PUBLIC_KEY")
                     langfuse_host = os.environ.get("LANGFUSE_BASE_URL")
                     print(f"LANGFUSE_PUBLIC_KEY: {langfuse_pk}")
@@ -171,7 +172,9 @@ class AdkAgent(agent_base.BaseAgent):
                     except Exception as e:
                         print(f"Failed to instrument Google ADK: {e}")
             except Exception as e:
-                print(f"Error checking observability config for ADK instrumentation: {e}")
+                print(
+                    f"Error checking observability config for ADK instrumentation: {e}"
+                )
 
         # Initialize Session Service
         await self._initialize_session_service()

idun_agent_engine/agent/langgraph/langgraph.py

@@ -202,7 +202,7 @@ class LanggraphAgent(agent_base.BaseAgent):
             self._agent_instance = graph_builder.compile(
                 checkpointer=self._checkpointer, store=self._store
             )
-        elif isinstance(graph_builder, CompiledStateGraph):
+        elif isinstance(graph_builder, CompiledStateGraph): # TODO: to remove, dirty fix for template deepagent langgraph
             self._agent_instance = graph_builder
 
         self._copilotkit_agent_instance = LangGraphAGUIAgent(

idun_agent_engine/core/app_factory.py

@@ -10,12 +10,12 @@ from typing import Any
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
+from .._version import __version__
 from ..server.lifespan import lifespan
 from ..server.routers.agent import agent_router
 from ..server.routers.base import base_router
 from .config_builder import ConfigBuilder
 from .engine_config import EngineConfig
-from .._version import __version__
 
 
 def create_app(

idun_agent_engine/core/config_builder.py

@@ -8,24 +8,24 @@ import os
 from pathlib import Path
 from typing import Any
 
-from idun_agent_schema.engine.guardrails import Guardrails as GuardrailsV1
 import yaml
+from idun_agent_schema.engine.adk import AdkAgentConfig
 from idun_agent_schema.engine.agent_framework import AgentFramework
+from idun_agent_schema.engine.guardrails_v2 import GuardrailsV2 as Guardrails
 from idun_agent_schema.engine.haystack import HaystackAgentConfig
 from idun_agent_schema.engine.langgraph import (
     LangGraphAgentConfig,
     SqliteCheckpointConfig,
 )
-from idun_agent_schema.engine.adk import AdkAgentConfig
 from idun_agent_schema.engine.mcp_server import MCPServer
 from idun_agent_schema.engine.observability_v2 import ObservabilityConfig
-from idun_agent_schema.engine.guardrails_v2 import GuardrailsV2 as Guardrails
-from idun_agent_engine.server.server_config import ServerAPIConfig
+from idun_agent_schema.manager.guardrail_configs import convert_guardrail
 from yaml import YAMLError
 
+from idun_agent_engine.server.server_config import ServerAPIConfig
+
 from ..agent.base import BaseAgent
 from .engine_config import AgentConfig, EngineConfig, ServerConfig
-from idun_agent_schema.manager.guardrail_configs import convert_guardrail
 
 
 class ConfigBuilder:
@@ -518,6 +518,9 @@ class ConfigBuilder:
     def load_from_file(config_path: str = "config.yaml") -> EngineConfig:
         """Load configuration from a YAML file and return a validated EngineConfig.
 
+        Sets IDUN_CONFIG_PATH environment variable to enable MCP helper functions
+        (get_adk_tools, get_langchain_tools) to automatically discover the config file.
+
         Args:
             config_path: Path to the configuration YAML file
 
@@ -533,6 +536,9 @@ class ConfigBuilder:
             # Resolve relative to the current working directory
             path = Path.cwd() / path
 
+        # Set IDUN_CONFIG_PATH for MCP helpers to discover
+        os.environ["IDUN_CONFIG_PATH"] = str(path)
+
         with open(path) as f:
             config_data = yaml.safe_load(f)
 

idun_agent_engine/guardrails/guardrails_hub/__init__.py

@@ -1,5 +1,5 @@
 """Guardrails Hub integration module."""
 
-from .guardrails_hub import GuardrailsHubGuardrail
+from .guardrails_hub import GuardrailsHubGuard
 
-__all__ = ["GuardrailsHubGuardrail"]
+__all__ = ["GuardrailsHubGuard"]

idun_agent_engine/mcp/__init__.py

@@ -1,5 +1,21 @@
 """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"]
+from .helpers import (
+    get_adk_tools_from_api,
+    get_adk_tools_from_file,
+    get_adk_tools,
+    get_langchain_tools,
+    get_langchain_tools_from_api,
+    get_langchain_tools_from_file,
+)
+
+__all__ = [
+    "MCPClientRegistry",
+    "get_adk_tools_from_api",
+    "get_adk_tools_from_file",
+    "get_adk_tools",
+    "get_langchain_tools",
+    "get_langchain_tools_from_api",
+    "get_langchain_tools_from_file",
+]

idun_agent_engine/mcp/helpers.py

@@ -6,36 +6,53 @@ 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.
 
+def _extract_mcp_configs(config_data: dict[str, Any]) -> list[MCPServer]:
+    """Parse MCP server configs from a config dictionary."""
     mcp_configs_data = config_data.get("mcp_servers") or config_data.get("mcpServers")
-
     if not mcp_configs_data:
         return []
+    return [MCPServer.model_validate(c) for c in mcp_configs_data]
+
+
+def _unwrap_engine_config(config_data: dict[str, Any]) -> dict[str, Any]:
+    """Return engine-level config if wrapped under engine_config."""
+    if not isinstance(config_data, dict):
+        raise ValueError("Configuration payload is empty or invalid")
+    if "engine_config" in config_data:
+        return config_data["engine_config"]
+    return config_data
+
 
-    mcp_configs = [MCPServer.model_validate(c) for c in mcp_configs_data]
-    registry = MCPClientRegistry(mcp_configs)
+def _build_registry(config_data: dict[str, Any]) -> MCPClientRegistry | None:
+    """Instantiate an MCP client registry from config data."""
+    mcp_configs = _extract_mcp_configs(config_data)
+    if not mcp_configs:
+        return None
+    return MCPClientRegistry(mcp_configs)
 
+
+def _get_toolsets_from_data(config_data: dict[str, Any]) -> list[Any]:
+    """Internal helper to extract ADK toolsets from config dictionary."""
+    registry = _build_registry(config_data)
+    if not registry:
+        return []
     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.
+async def _get_langchain_tools_from_data(config_data: dict[str, Any]) -> list[Any]:
+    """Internal helper to extract LangChain tools from config dictionary."""
+    registry = _build_registry(config_data)
+    if not registry:
+        return []
+    return await registry.get_tools()
 
-    Returns:
-        List of initialized ADK McpToolset instances.
-    """
+
+def _load_config_from_file(config_path: str | Path) -> dict[str, Any]:
+    """Load YAML config (optionally wrapped in engine_config) from disk."""
     path = Path(config_path)
     if not path.exists():
         raise FileNotFoundError(f"Configuration file not found at {path}")
@@ -43,55 +60,130 @@ def get_adk_tools_from_file(config_path: str | Path) -> list[Any]:
     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.
+    return _unwrap_engine_config(config_data)
 
-    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.
-    """
+def _fetch_config_from_api() -> dict[str, Any]:
+    """Fetch configuration from the Idun Manager API."""
     api_key = os.environ.get("IDUN_AGENT_API_KEY")
     manager_host = os.environ.get("IDUN_MANAGER_HOST")
+
+    if not api_key:
+        raise ValueError("Environment variable 'IDUN_AGENT_API_KEY' is not set")
+
+    if not manager_host:
+        raise ValueError("Environment variable 'IDUN_MANAGER_HOST' is not set")
+
     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)
-
+        return _unwrap_engine_config(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]:
+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.
+    """
+    config_data = _load_config_from_file(config_path)
+    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.
 
+    Returns:
+        List of initialized ADK McpToolset instances.
+    """
+    config_data = _fetch_config_from_api()
+    return _get_toolsets_from_data(config_data)
+
+
+def get_adk_tools(config_path: str | Path | None = None) -> list[Any]:
+    """
+    Returns ADK toolsets using config from file when provided, from IDUN_CONFIG_PATH env var, or from API.
+
+    The function resolves configuration in the following order:
+    1. Uses the provided config_path if specified
+    2. Uses IDUN_CONFIG_PATH environment variable if set
+    3. Falls back to fetching from Idun Manager API
+
     Args:
-        agent_api_key: The API key for authentication.
-        manager_url: The base URL of the Idun Manager (e.g. http://localhost:8000).
+        config_path: Optional path to configuration YAML file. If provided, takes precedence.
 
     Returns:
         List of initialized ADK McpToolset instances.
+
+    Raises:
+        ValueError: If no config source is available or API credentials are missing.
+        FileNotFoundError: If specified config file doesn't exist.
     """
+    if config_path:
+        return get_adk_tools_from_file(config_path)
+
+    # Check for IDUN_CONFIG_PATH environment variable
+    env_config_path = os.environ.get("IDUN_CONFIG_PATH")
+    if env_config_path:
+        return get_adk_tools_from_file(env_config_path)
+
     return get_adk_tools_from_api()
+
+
+async def get_langchain_tools_from_file(config_path: str | Path) -> list[Any]:
+    """
+    Loads MCP configurations from a YAML file and returns LangChain tool instances.
+    """
+    config_data = _load_config_from_file(config_path)
+    return await _get_langchain_tools_from_data(config_data)
+
+
+async def get_langchain_tools_from_api() -> list[Any]:
+    """
+    Fetches configuration from the Idun Manager API and returns LangChain tool instances.
+    """
+    config_data = _fetch_config_from_api()
+    return await _get_langchain_tools_from_data(config_data)
+
+
+async def get_langchain_tools(config_path: str | Path | None = None) -> list[Any]:
+    """
+    Returns LangChain tool instances using config from file when provided, from IDUN_CONFIG_PATH env var, or from API.
+
+    The function resolves configuration in the following order:
+    1. Uses the provided config_path if specified
+    2. Uses IDUN_CONFIG_PATH environment variable if set
+    3. Falls back to fetching from Idun Manager API
+
+    Args:
+        config_path: Optional path to configuration YAML file. If provided, takes precedence.
+
+    Returns:
+        List of initialized LangChain tool instances.
+
+    Raises:
+        ValueError: If no config source is available or API credentials are missing.
+        FileNotFoundError: If specified config file doesn't exist.
+    """
+    if config_path:
+        return await get_langchain_tools_from_file(config_path)
+
+    # Check for IDUN_CONFIG_PATH environment variable
+    env_config_path = os.environ.get("IDUN_CONFIG_PATH")
+    if env_config_path:
+        return await get_langchain_tools_from_file(env_config_path)
+
+    return await get_langchain_tools_from_api()

idun_agent_engine/mcp/registry.py

@@ -79,7 +79,13 @@ class MCPClientRegistry:
             raise RuntimeError("MCP client registry is not enabled.")
         return await self._client.get_tools(server_name=name)
 
-    def get_adk_toolsets(self) -> list["McpToolset"]:
+    async def get_langchain_tools(self, name: str | None = None) -> list[Any]:
+        """
+        Alias for get_tools to make intent explicit when using LangChain/LangGraph agents.
+        """
+        return await self.get_tools(name=name)
+
+    def get_adk_toolsets(self) -> list[Any]:
         """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.")

idun_agent_engine/server/lifespan.py

@@ -15,6 +15,7 @@ from ..mcp import MCPClientRegistry
 from idun_agent_schema.engine.guardrails import Guardrails, Guardrail
 
 from ..guardrails.base import BaseGuardrail
+from ..telemetry import get_telemetry, sanitize_telemetry_config
 
 
 def _parse_guardrails(guardrails_obj: Guardrails) -> Sequence[BaseGuardrail]:
@@ -98,9 +99,30 @@ async def lifespan(app: FastAPI):
 
     await configure_app(app, app.state.engine_config)
 
+    try:
+        telemetry = get_telemetry()
+        app.state.telemetry = telemetry
+        agent = getattr(app.state, "agent", None)
+        telemetry.capture(
+            "engine started",
+            properties={
+                "agent_type": type(agent).__name__ if agent is not None else None,
+                "has_agent": agent is not None,
+                "engine_config": sanitize_telemetry_config(app.state.engine_config),
+            },
+        )
+    except Exception as e:
+        print(f"⚠️ Warning: Failed to start telemetry: {e}")
+        app.state.telemetry = None
+
     yield
 
     # Clean up on shutdown
     print("🔄 Idun Agent Engine shutting down...")
+    telemetry = getattr(app.state, "telemetry", None)
+    if telemetry is not None:
+        telemetry.capture("engine stopped")
     await cleanup_agent(app)
+    if telemetry is not None:
+        telemetry.shutdown()
     print("✅ Agent resources cleaned up successfully.")

idun_agent_engine/telemetry/__init__.py

@@ -0,0 +1,19 @@
+"""Telemetry package for Idun Agent Engine."""
+
+from __future__ import annotations
+
+from .telemetry import IdunTelemetry, sanitize_telemetry_config
+
+_telemetry_singleton: IdunTelemetry | None = None
+
+
+def get_telemetry() -> IdunTelemetry:
+    """Return the process-wide telemetry singleton."""
+
+    global _telemetry_singleton
+    if _telemetry_singleton is None:
+        _telemetry_singleton = IdunTelemetry()
+    return _telemetry_singleton
+
+
+__all__ = ["IdunTelemetry", "get_telemetry", "sanitize_telemetry_config"]

idun_agent_engine/telemetry/config.py

@@ -0,0 +1,29 @@
+"""Telemetry configuration utilities."""
+
+from __future__ import annotations
+
+import os
+
+IDUN_TELEMETRY_ENABLED_ENV = "IDUN_TELEMETRY_ENABLED"
+
+
+def telemetry_enabled(environ: dict[str, str] | None = None) -> bool:
+    """Return whether telemetry is enabled.
+
+    Telemetry is ON by default. Users can disable it by setting the environment
+    variable `IDUN_TELEMETRY_ENABLED` to a falsy value (e.g. "false", "0", "no").
+    """
+
+    env = os.environ if environ is None else environ
+    raw = env.get(IDUN_TELEMETRY_ENABLED_ENV)
+    if raw is None:
+        return True
+
+    value = raw.strip().lower()
+    if value in {"0", "false", "no", "off", "disable", "disabled"}:
+        return False
+    if value in {"1", "true", "yes", "on", "enable", "enabled"}:
+        return True
+
+    # Unknown values default to enabled (opt-out).
+    return True