idun-agent-engine 0.3.9__tar.gz → 0.4.1__tar.gz

{idun_agent_engine-0.3.9 → idun_agent_engine-0.4.1}/PKG-INFO

@@ -1,17 +1,17 @@
 Metadata-Version: 2.4
 Name: idun-agent-engine
-Version: 0.3.9
+Version: 0.4.1
 Summary: Python SDK and runtime to serve AI agents with FastAPI, LangGraph, and observability.
 Project-URL: Homepage, https://github.com/geoffreyharrazi/idun-agent-platform
 Project-URL: Repository, https://github.com/geoffreyharrazi/idun-agent-platform
 Project-URL: Documentation, https://github.com/geoffreyharrazi/idun-agent-platform/tree/main/libs/idun_agent_engine
 Project-URL: Issues, https://github.com/geoffreyharrazi/idun-agent-platform/issues
 Author-email: Geoffrey HARRAZI <geoffreyharrazi@gmail.com>
-License-Expression: MIT
+License-Expression: GPL-3.0-only
 Keywords: agents,fastapi,langgraph,llm,observability,sdk
 Classifier: Framework :: FastAPI
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
@@ -31,12 +31,12 @@ Requires-Dist: deepagents<1.0.0,>=0.2.8
 Requires-Dist: fastapi<0.116.0,>=0.115.0
 Requires-Dist: google-adk<2.0.0,>=1.19.0
 Requires-Dist: google-cloud-logging<4.0.0,>=3.10.0
-Requires-Dist: guardrails-ai<0.8.0,>=0.7.0
+Requires-Dist: guardrails-ai<0.8.0,>=0.7.2
 Requires-Dist: httpx<0.29.0,>=0.28.1
 Requires-Dist: idun-agent-schema<1.0.0,>=0.3.8
 Requires-Dist: langchain-core<2.0.0,>=1.0.0
 Requires-Dist: langchain-google-vertexai<4.0.0,>=2.0.27
-Requires-Dist: langchain-mcp-adapters<0.2.0,>=0.1.0
+Requires-Dist: langchain-mcp-adapters<0.3.0,>=0.2.0
 Requires-Dist: langchain<2.0.0,>=1.0.0
 Requires-Dist: langfuse-haystack>=2.3.0
 Requires-Dist: langfuse<4.0.0,>=2.60.8
@@ -51,12 +51,16 @@ Requires-Dist: openinference-instrumentation-mcp<2.0.0,>=1.0.0
 Requires-Dist: openinference-instrumentation-vertexai<1.0.0,>=0.1.0
 Requires-Dist: opentelemetry-exporter-gcp-trace<2.0.0,>=1.6.0
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0.0,>=1.22.0
+Requires-Dist: platformdirs<5.0.0,>=4.0.0
+Requires-Dist: posthog<8.0.0,>=7.0.0
 Requires-Dist: psycopg-binary<4.0.0,>=3.3.0
 Requires-Dist: pydantic<3.0.0,>=2.11.7
 Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: pyyaml<7.0.0,>=6.0.0
 Requires-Dist: sqlalchemy<3.0.0,>=2.0.36
 Requires-Dist: streamlit<2.0.0,>=1.47.1
 Requires-Dist: tavily-python<0.8.0,>=0.7.9
+Requires-Dist: textual<7.4.0,>=7.3.0
 Requires-Dist: uvicorn<0.36.0,>=0.35.0
 Description-Content-Type: text/markdown
 
@@ -72,7 +76,7 @@ Idun Agent Engine is a lightweight runtime and SDK that wraps your agent with a
 pip install idun-agent-engine
 ```
 
-- Requires Python 3.13
+- Requires Python 3.12+
 - Ships with FastAPI, Uvicorn, LangGraph, SQLite checkpointing, and optional observability hooks
 
 ## Quickstart
@@ -319,9 +323,9 @@ from idun_agent_engine import (
 
 Issues and PRs are welcome. See the repository:
 
-- Repo: `https://github.com/geoffreyharrazi/idun-agent-platform`
+- Repo: `https://github.com/Idun-Group/idun-agent-platform`
 - Package path: `libs/idun_agent_engine`
-- Open an issue: `https://github.com/geoffreyharrazi/idun-agent-platform/issues`
+- Open an issue: `https://github.com/Idun-Group/idun-agent-platform/issues`
 
 Run locally:
 

{idun_agent_engine-0.3.9 → idun_agent_engine-0.4.1}/README.md

@@ -10,7 +10,7 @@ Idun Agent Engine is a lightweight runtime and SDK that wraps your agent with a
 pip install idun-agent-engine
 ```
 
-- Requires Python 3.13
+- Requires Python 3.12+
 - Ships with FastAPI, Uvicorn, LangGraph, SQLite checkpointing, and optional observability hooks
 
 ## Quickstart
@@ -257,9 +257,9 @@ from idun_agent_engine import (
 
 Issues and PRs are welcome. See the repository:
 
-- Repo: `https://github.com/geoffreyharrazi/idun-agent-platform`
+- Repo: `https://github.com/Idun-Group/idun-agent-platform`
 - Package path: `libs/idun_agent_engine`
-- Open an issue: `https://github.com/geoffreyharrazi/idun-agent-platform/issues`
+- Open an issue: `https://github.com/Idun-Group/idun-agent-platform/issues`
 
 Run locally:
 

{idun_agent_engine-0.3.9 → idun_agent_engine-0.4.1}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "idun-agent-engine"
-version = "0.3.9"
+version = "0.4.1"
 description = "Python SDK and runtime to serve AI agents with FastAPI, LangGraph, and observability."
 authors = [{ name = "Geoffrey HARRAZI", email = "geoffreyharrazi@gmail.com" }]
 requires-python = ">=3.12,<3.14"
 readme = "README.md"
-license = "MIT"
+license = "GPL-3.0-only"
 keywords = [
     "agents",
     "langgraph",
@@ -15,7 +15,7 @@ keywords = [
     "observability",
 ]
 classifiers = [
-    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.12",
@@ -32,7 +32,7 @@ classifiers = [
 dependencies = [
     "tavily-python>=0.7.9,<0.8.0",
     "deepagents>=0.2.8,<1.0.0",
-    "guardrails-ai>=0.7.0, <0.8.0",
+    "guardrails-ai>=0.7.2, <0.8.0",
     "fastapi>=0.115.0,<0.116.0",
     "uvicorn>=0.35.0,<0.36.0",
     "langgraph>=1.0.0,<2.0.0",
@@ -50,6 +50,7 @@ dependencies = [
     "arize-phoenix-otel>=0.2.0,<1.0.0",
     "openinference-instrumentation-langchain>=0.1.13,<1.0.0",
     "langchain>=1.0.0,<2.0.0",
+    "textual>=7.3.0,<7.4.0",
     # Pin <12: 12.x currently depends on placeholder jmespath==99.99.99 and fails in Docker
     "arize-phoenix>=11.22.0,<12.0.0",
     "idun-agent-schema>=0.3.8,<1.0.0",
@@ -60,7 +61,7 @@ dependencies = [
     "sqlalchemy>=2.0.36,<3.0.0",
     "ag-ui-langgraph>=0.0.20,<0.1.0",
     "copilotkit>=0.1.72,<0.2.0",
-    "langchain-mcp-adapters>=0.1.0,<0.2.0",
+    "langchain-mcp-adapters>=0.2.0,<0.3.0",
     "ag-ui-adk>=0.3.4,<0.4.0",
     "opentelemetry-exporter-gcp-trace>=1.6.0,<2.0.0",
     "openinference-instrumentation-guardrails>=0.1.0,<1.0.0",
@@ -71,6 +72,9 @@ dependencies = [
     "opentelemetry-exporter-otlp-proto-http>=1.22.0,<2.0.0",
     "mcp>=1.0.0,<2.0.0",
     "psycopg-binary>=3.3.0,<4.0.0",
+    "platformdirs>=4.0.0,<5.0.0",
+    "posthog>=7.0.0,<8.0.0",
+    "PyYAML>=6.0.0,<7.0.0",
 ]
 
 
@@ -104,7 +108,15 @@ include = [
 ]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/idun_agent_engine", "src/idun_platform_cli"]
+include = [
+  "src/idun_agent_engine",
+  "src/idun_agent_engine/py.typed",
+  "src/idun_platform_cli",
+]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/idun_agent_engine" = "idun_agent_engine"
+"src/idun_platform_cli" = "idun_platform_cli"
 
 [build-system]
 requires = ["hatchling"]

{idun_agent_engine-0.3.9 → idun_agent_engine-0.4.1}/src/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-0.3.9 → idun_agent_engine-0.4.1}/src/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-0.3.9 → idun_agent_engine-0.4.1}/src/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-0.3.9 → idun_agent_engine-0.4.1}/src/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-0.4.1/src/idun_agent_engine/guardrails/guardrails_hub/__init__.py

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

idun_agent_engine-0.4.1/src/idun_agent_engine/mcp/__init__.py

@@ -0,0 +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,
+    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-0.4.1/src/idun_agent_engine/mcp/helpers.py

@@ -0,0 +1,189 @@
+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 _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
+
+
+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
+
+
+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()
+
+
+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}")
+
+    with open(path) as f:
+        config_data = yaml.safe_load(f)
+
+    return _unwrap_engine_config(config_data)
+
+
+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)
+        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_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:
+        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-0.3.9 → idun_agent_engine-0.4.1}/src/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-0.3.9 → idun_agent_engine-0.4.1}/src/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-0.4.1/src/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-0.4.1/src/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