idun-agent-engine 0.3.9__py3-none-any.whl → 0.4.0__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.0"

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

@@ -4,28 +4,27 @@ This module provides a fluent API for building configuration objects using Pydan
 This approach ensures type safety, validation, and consistency with the rest of the codebase.
 """
 
-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:

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,52 @@ 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]
 
-    mcp_configs = [MCPServer.model_validate(c) for c in mcp_configs_data]
-    registry = MCPClientRegistry(mcp_configs)
 
+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
+
+
+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 +59,89 @@ 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 _unwrap_engine_config(config_data)
 
-    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.
-    """
+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_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() -> list[Any]:
+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.
+    """
+    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, otherwise from API.
 
     Returns:
         List of initialized ADK McpToolset instances.
     """
+    if config_path:
+        return get_adk_tools_from_file(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, otherwise from API.
+    """
+    if config_path:
+        return await get_langchain_tools_from_file(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

idun_agent_engine/telemetry/telemetry.py

@@ -0,0 +1,248 @@
+"""Non-blocking telemetry for Idun Agent Engine.
+
+Telemetry is ON by default and can be disabled with `IDUN_TELEMETRY_ENABLED=false`.
+
+We persist a stable `distinct_id` in the OS cache directory at:
+`<cache_dir>/idun/telemetry_user_id`
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+import sys
+import threading
+import uuid
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_cache_dir
+
+from .config import telemetry_enabled
+
+_POSTHOG_HOST = "https://us.i.posthog.com"
+_POSTHOG_PROJECT_API_KEY = "phc_mpAplkH6w5zK1aSkkG0IL5Ys55m6X34BFvGozB2NqPw"
+_DISTINCT_ID_ENV = "IDUN_TELEMETRY_DISTINCT_ID"
+_CACHE_APP_NAME = "idun"
+_CACHE_DISTINCT_ID_FILE = "telemetry_user_id"
+_MAX_VALUE_LENGTH = 200
+_SENSITIVE_KEY_FRAGMENTS = (
+    "api_key",
+    "apikey",
+    "access_key",
+    "accesskey",
+    "private_key",
+    "privatekey",
+    "secret",
+    "token",
+    "password",
+    "passphrase",
+    "client_secret",
+    "clientsecret",
+    "bearer",
+    "authorization",
+)
+
+
+def _is_sensitive_key(key: str) -> bool:
+    normalized = re.sub(r"[^a-z0-9]+", "_", key.lower())
+    return any(fragment in normalized for fragment in _SENSITIVE_KEY_FRAGMENTS)
+
+
+def _is_private_key_value(value: str) -> bool:
+    upper_value = value.upper()
+    return "PRIVATE KEY" in upper_value or "BEGIN OPENSSH PRIVATE KEY" in upper_value
+
+
+def _truncate_value(value: str) -> str:
+    if len(value) <= _MAX_VALUE_LENGTH:
+        return value
+    return value[:_MAX_VALUE_LENGTH]
+
+
+def sanitize_telemetry_config(value: Any) -> Any:
+    """Return a telemetry-safe copy of config objects."""
+    if hasattr(value, "model_dump") and callable(value.model_dump):
+        value = value.model_dump()  # type: ignore[assignment]
+    elif hasattr(value, "dict") and callable(value.dict):
+        value = value.dict()  # type: ignore[assignment]
+
+    if isinstance(value, dict):
+        sanitized: dict[str, Any] = {}
+        for key, item in value.items():
+            if isinstance(key, str) and _is_sensitive_key(key):
+                sanitized[key] = "[redacted]"
+            else:
+                sanitized[key] = sanitize_telemetry_config(item)
+        return sanitized
+
+    if isinstance(value, (list, tuple, set)):
+        return [sanitize_telemetry_config(item) for item in value]
+
+    if isinstance(value, str):
+        if _is_private_key_value(value):
+            return "[redacted]"
+        return _truncate_value(value)
+
+    return value
+
+
+def _safe_read_text(path: Path) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except Exception:
+        return None
+
+
+def _safe_write_text(path: Path, text: str) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+    except Exception:
+        # Best-effort only.
+        return
+
+
+def _get_or_create_distinct_id() -> str | None:
+    """Return a stable distinct id.
+
+    Preference order:
+    - `IDUN_TELEMETRY_DISTINCT_ID` (if set)
+    - A UUID persisted to `<cache_dir>/idun/telemetry_user_id`
+    """
+
+    raw = os.environ.get(_DISTINCT_ID_ENV)
+    if raw and raw.strip():
+        return raw.strip()
+
+    cache_dir = Path(user_cache_dir(_CACHE_APP_NAME))
+    id_path = cache_dir / _CACHE_DISTINCT_ID_FILE
+
+    existing = _safe_read_text(id_path)
+    if existing:
+        return existing
+
+    new_id = str(uuid.uuid4())
+    _safe_write_text(id_path, new_id)
+    return new_id
+
+
+def _common_properties() -> dict[str, Any]:
+    from .._version import __version__
+
+    return {
+        "library": "idun-agent-engine",
+        "library_version": __version__,
+        "python_version": platform.python_version(),
+        "python_implementation": platform.python_implementation(),
+        "platform": sys.platform,
+        "os": platform.system(),
+        "os_version": platform.release(),
+    }
+
+
+@dataclass(slots=True)
+class IdunTelemetry:
+    """Non-blocking telemetry client."""
+
+    enabled: bool = field(default_factory=telemetry_enabled)
+    _executor: ThreadPoolExecutor | None = field(default=None, init=False, repr=False)
+    _client: Any | None = field(default=None, init=False, repr=False)
+    _client_lock: threading.Lock = field(
+        default_factory=threading.Lock, init=False, repr=False
+    )
+    _distinct_id: str | None = field(default=None, init=False, repr=False)
+
+    def _ensure_executor(self) -> ThreadPoolExecutor:
+        if self._executor is None:
+            self._executor = ThreadPoolExecutor(
+                max_workers=1, thread_name_prefix="idun-telemetry"
+            )
+        return self._executor
+
+    def _get_client(self) -> Any | None:
+        if not self.enabled:
+            return None
+        if self._client is not None:
+            return self._client
+
+        with self._client_lock:
+            if self._client is not None:
+                return self._client
+            try:
+                from posthog import Posthog
+            except Exception:
+                # Dependency missing or import failure should not break runtime.
+                return None
+
+            client = Posthog(_POSTHOG_PROJECT_API_KEY, host=_POSTHOG_HOST)
+            self._client = client
+            self._distinct_id = _get_or_create_distinct_id()
+            return self._client
+
+    def capture(self, event: str, properties: dict[str, Any] | None = None) -> Future[None] | None:
+        """Capture an event asynchronously (best-effort)."""
+
+        if not self.enabled:
+            return None
+
+        executor = self._ensure_executor()
+
+        def _send() -> None:
+            client = self._get_client()
+            if client is None:
+                return
+
+            merged: dict[str, Any] = _common_properties()
+            if properties:
+                merged.update(properties)
+
+            try:
+                if self._distinct_id:
+                    client.capture(
+                        event=event,
+                        distinct_id=self._distinct_id,
+                        properties=merged,
+                    )
+                else:
+                    client.capture(event=event, properties=merged)
+            except Exception:
+                # Never fail user code because of telemetry.
+                return
+
+        try:
+            return executor.submit(_send)
+        except Exception:
+            return None
+
+    def shutdown(self, timeout_seconds: float = 1.0) -> None:
+        """Best-effort flush/shutdown without blocking application shutdown."""
+
+        executor = self._executor
+        client = self._client
+
+        if executor is None:
+            return
+
+        def _shutdown_client() -> None:
+            try:
+                if client is not None:
+                    shutdown_fn = getattr(client, "shutdown", None)
+                    if callable(shutdown_fn):
+                        shutdown_fn()
+            except Exception:
+                return
+
+        try:
+            fut = executor.submit(_shutdown_client)
+            fut.result(timeout=timeout_seconds)
+        except Exception:
+            pass
+        finally:
+            try:
+                executor.shutdown(wait=False, cancel_futures=False)
+            except Exception:
+                pass