idun-agent-engine 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

idun_agent_engine/observability/base.py

@@ -0,0 +1,111 @@
+"""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
+
+
+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: ObservabilityConfig | dict[str, Any] | None,
+) -> dict[str, Any]:
+    if config is None:
+        return {"enabled": False}
+    if isinstance(config, ObservabilityConfig):
+        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: ObservabilityConfig | dict[str, Any] | None,
+) -> tuple[ObservabilityHandlerBase | None, dict[str, Any] | None]:
+    """Factory to create an observability handler based on provider.
+
+    Accepts either an `ObservabilityConfig` 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}
+
+    if provider == "langfuse":
+        from .langfuse.langfuse_handler import LangfuseHandler
+
+        handler = LangfuseHandler(options)
+        return handler, {
+            "enabled": True,
+            "provider": "langfuse",
+            "host": os.getenv("LANGFUSE_HOST"),
+            "run_name": handler.get_run_name(),
+        }
+
+    if provider == "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",
+        }
+
+    return None, {
+        "enabled": False,
+        "provider": provider,
+        "error": "Unsupported provider",
+    }

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,72 @@
+"""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_HOST")
+        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_HOST"] = 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.callback import CallbackHandler
+            from langfuse.client import Langfuse
+
+            self._langfuse_client = Langfuse()
+
+            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:
+                pass
+
+            self._callbacks = [CallbackHandler()]
+        except Exception:
+            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://127.0.0.1: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/py.typed

@@ -1 +0,0 @@
-# Marker file to indicate that this package is PEP 561 typed

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,23 @@
+"""Dependency injection helpers for FastAPI routes."""
+
+from fastapi import Request
+
+from ..core.config_builder import ConfigBuilder
+
+
+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

idun_agent_engine/server/lifespan.py

@@ -0,0 +1,42 @@
+"""Server lifespan management utilities.
+
+Initializes the agent at startup and cleans up resources on shutdown.
+"""
+
+import inspect
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from ..core.config_builder import ConfigBuilder
+
+
+@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...")
+    engine_config = app.state.engine_config
+
+    # Use ConfigBuilder's centralized agent initialization
+    agent_instance = await ConfigBuilder.initialize_agent_from_config(engine_config)
+
+    # Store both in app state
+    app.state.agent = agent_instance
+    app.state.config = engine_config
+
+    agent_name = getattr(agent_instance, "name", "Unknown")
+    print(f"✅ Agent '{agent_name}' initialized and ready to serve!")
+
+    yield
+
+    # Clean up on shutdown
+    print("🔄 Idun Agent Engine shutting down...")
+    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
+    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"]

idun_agent_engine/server/routers/agent.py

@@ -0,0 +1,68 @@
+"""Agent routes for invoking and streaming agent responses."""
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi.responses import StreamingResponse
+from idun_agent_schema.engine.api import ChatRequest, ChatResponse
+
+from idun_agent_engine.agent.base import BaseAgent
+from idun_agent_engine.server.dependencies import get_agent
+
+logging.basicConfig(
+    format="%(asctime)s %(levelname)-8s %(message)s",
+    level=logging.INFO,
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+logger = logging.getLogger(__name__)
+agent_router = APIRouter()
+
+
+@agent_router.get("/config")
+async def get_config(request: Request):
+    """Get the current agent configuration."""
+    logger.debug("Fetching agent config..")
+    if not hasattr(request.app.state, "engine_config"):
+        logger.error("Error retrieving the engine config from the api. ")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Configuration not available"
+        )
+
+    config = request.app.state.engine_config.agent
+    logger.info(f"Fetched config for agent: {config}")
+    return {"config": config}
+
+
+@agent_router.post("/invoke", response_model=ChatResponse)
+async def invoke(
+    request: ChatRequest,
+    agent: Annotated[BaseAgent, Depends(get_agent)],
+):
+    """Process a chat message with the agent without streaming."""
+    try:
+        message = {"query": request.query, "session_id": request.session_id}
+        response_content = await agent.invoke(message)
+
+        return ChatResponse(session_id=request.session_id, response=response_content)
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@agent_router.post("/stream")
+async def stream(
+    request: ChatRequest,
+    agent: Annotated[BaseAgent, Depends(get_agent)],
+):
+    """Process a message with the agent, streaming ag-ui events."""
+    try:
+
+        async def event_stream():
+            message = {"query": request.query, "session_id": request.session_id}
+            async for event in agent.stream(message):
+                yield f"data: {event.model_dump_json()}\n\n"
+
+        return StreamingResponse(event_stream(), media_type="text/event-stream")
+    except Exception as e:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(e)) from e

idun_agent_engine/server/routers/base.py

@@ -0,0 +1,60 @@
+"""Base routes for service health and landing info."""
+
+from fastapi import APIRouter
+
+from ..._version import __version__
+
+base_router = APIRouter()
+
+
+@base_router.get("/health")
+def health_check():
+    """Health check endpoint for monitoring and load balancers."""
+    return {"status": "healthy", "engine_version": __version__}
+
+
+# Add a root endpoint with helpful information
+@base_router.get("/")
+def read_root():
+    """Root endpoint with basic information about the service."""
+    return {
+        "message": "Welcome to your Idun Agent Engine server!",
+        "docs": "/docs",
+        "health": "/health",
+        "agent_endpoints": {"invoke": "/agent/invoke", "stream": "/agent/stream"},
+    }
+
+
+# # Add info endpoint for detailed server and agent information
+# @base_router.get("/info")
+# def get_info(request: Request):
+#     """Get detailed information about the server and loaded agent."""
+#     info = {
+#         "engine": {
+#             "name": "Idun Agent Engine",
+#             "version": __version__,
+#             "description": "A framework for building and deploying conversational AI agents"
+#         },
+#         "server": {
+#             "status": "running",
+#             "endpoints": {
+#                 "health": "/health",
+#                 "docs": "/docs",
+#                 "redoc": "/redoc",
+#                 "agent_invoke": "/agent/invoke",
+#                 "agent_stream": "/agent/stream"
+#             }
+#         }
+#     }
+
+#     # Add agent information if available in app state
+#     if hasattr(request.app.state, "config") and request.app.state.config:
+#         config = request.app.state.config
+#         info["agent"] = {
+#             "type": config.agent.type,
+#             "name": config.agent.config.get("name", "Unknown"),
+#             "status": "loaded"
+#         }
+#         info["server"]["port"] = config.server.api.port
+
+#     return info

idun_agent_engine/server/server_config.py

@@ -0,0 +1,8 @@
+"""Compatibility re-exports for server configuration models."""
+
+from idun_agent_schema.engine.server import (  # noqa: F401
+    ServerAPIConfig,
+    ServerConfig,
+)
+
+__all__ = ["ServerAPIConfig", "ServerConfig"]