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

idun_agent_engine/__init__.py

@@ -1,30 +1,8 @@
-"""Idun Agent Engine - A framework for building and deploying conversational AI agents.
+"""Idun Agent Engine public API.
 
-This Engine provides a unified interface for different agent frameworks (LangGraph, CrewAI, etc.)
-and automatically generates a production-ready FastAPI server for your agents.
-
-Quick Start:
-    from idun_agent_engine import ConfigBuilder, create_app, run_server
-
-    # Method 1: Using ConfigBuilder (Recommended)
-    config = (ConfigBuilder()
-             .with_langgraph_agent(name="My Agent", graph_definition="agent.py:graph")
-             .build())
-    app = create_app(engine_config=config)
-    run_server(app)
-
-    # Method 2: Using YAML config file
-    app = create_app(config_path="config.yaml")
-    run_server(app, port=8000)
-
-    # Method 3: One-liner from config file
-    from idun_agent_engine.core.server_runner import run_server_from_config
-    run_server_from_config("config.yaml")
-
-For more advanced usage, see the documentation.
+Exports top-level helpers for convenience imports in examples and user code.
 """
 
-# Version information - import from separate module to avoid circular imports
 from ._version import __version__
 from .agent.base import BaseAgent
 from .core.app_factory import create_app
@@ -35,7 +13,6 @@ from .core.server_runner import (
     run_server_from_config,
 )
 
-# Main public API
 __all__ = [
     "create_app",
     "run_server",

idun_agent_engine/_version.py

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

idun_agent_engine/agent/__init__.py

@@ -0,0 +1,10 @@
+"""Agent package exposing common base types.
+
+Re-exports:
+    - BaseAgent: abstract base for all agents
+    - BaseAgentConfig: base model for agent configuration
+"""
+
+from .base import BaseAgent
+
+__all__ = ["BaseAgent"]

idun_agent_engine/agent/base.py

@@ -0,0 +1,97 @@
+"""Agent base interfaces.
+
+Defines the abstract `BaseAgent` used by all agent implementations.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from idun_agent_schema.engine.agent import BaseAgentConfig
+
+
+class BaseAgent[ConfigType: BaseAgentConfig](ABC):
+    """Abstract base for agents pluggable into the Idun Agent Engine.
+
+    Implements the public protocol that concrete agent adapters must follow.
+    """
+
+    _configuration: ConfigType
+
+    @property
+    @abstractmethod
+    def id(self) -> str:
+        """Unique identifier for the agent instance."""
+        pass
+
+    @property
+    @abstractmethod
+    def agent_type(self) -> str:
+        """Type or category of the agent (e.g., 'LangGraph', 'ADK')."""
+        pass
+
+    @property
+    @abstractmethod
+    def agent_instance(self) -> Any:
+        """Get the underlying agent instance from the specific framework.
+
+        This might be set after initialization.
+        """
+        pass
+
+    @property
+    def configuration(self) -> ConfigType:
+        """Return current configuration settings for the agent.
+
+        This is typically the configuration used during initialization.
+        """
+        return self._configuration
+
+    @property
+    @abstractmethod
+    def infos(self) -> dict[str, Any]:
+        """General information about the agent instance (e.g., version, status, metadata)."""
+        pass
+
+    @abstractmethod
+    async def initialize(self, config: dict[str, Any]) -> None:
+        """Initialize the agent with a given configuration.
+
+        This method should set up the underlying agent framework instance.
+
+        Args:
+            config: A dictionary containing the agent's configuration.
+        """
+        pass
+
+    @abstractmethod
+    async def invoke(self, message: Any) -> Any:
+        """Process a single input message and return a response.
+
+        This should be an awaitable method if the underlying agent processes
+        asynchronously.
+
+        Args:
+            message: The input message for the agent.
+
+        Returns:
+            The agent's response.
+        """
+        pass
+
+    @abstractmethod
+    async def stream(self, message: Any) -> AsyncGenerator[Any]:
+        """Process a single input message and return an asynchronous stream.
+
+        Args:
+            message: The input message for the agent.
+
+        Yields:
+            Chunks of the agent's response.
+        """
+        # This is an async generator, so it needs `async def` and `yield`
+        # For the ABC, we can't have a `yield` directly in the abstract method body.
+        # The signature itself defines it as an async generator.
+        # Example: async for chunk in agent.stream(message): ...
+        if False:  # pragma: no cover (This is just to make it a generator type for static analysis)
+            yield

idun_agent_engine/agent/haystack/__init__.py

@@ -0,0 +1,9 @@
+"""LangGraph agent package."""
+
+from .haystack import HaystackAgent
+from .haystack_model import HaystackAgentConfig
+
+__all__ = [
+    "HaystackAgent",
+    "HaystackAgentConfig",
+]

idun_agent_engine/agent/haystack/haystack.py

@@ -0,0 +1,261 @@
+import importlib.util
+import logging
+import os
+import uuid
+from typing import Any
+
+os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"
+
+from haystack import Pipeline
+from haystack.components.agents import Agent
+from haystack.dataclasses import ChatMessage
+from haystack_integrations.components.connectors.langfuse import LangfuseConnector
+
+from idun_agent_engine.agent.base import BaseAgent
+from idun_agent_schema.engine.haystack import HaystackAgentConfig
+from idun_agent_engine.agent.haystack.utils import _parse_component_definition
+
+logging.basicConfig(
+    format="%(asctime)s %(levelname)-8s %(message)s",
+    level=logging.INFO,
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+logger = logging.getLogger(__name__)
+
+
+class HaystackAgent(BaseAgent):
+    """Haystack agent adapter implementing the BaseAgent protocol."""
+
+    def __init__(self):
+        """Initialize an unconfigured haystack agent with default state."""
+        self._id: str = str(uuid.uuid4())
+        self._agent_type: str = "haystack"
+        self._agent_instance: Any = None
+        self._configuration: HaystackAgentConfig | None = None
+        self._name: str = "Haystack Agent"
+        self._langfuse_tracing: bool = False
+        self._enable_tracing: bool = False
+        self._infos: dict[str, Any] = {
+            "status": "Uninitialized",
+            "name": self._name,
+            "id": self._id,
+        }
+        # TODO: input/output schema
+        # TODO: checkpointing/debugging
+
+    @property
+    def id(self) -> str:
+        """Returns the agent id."""
+        return self._id
+
+    @property
+    def agent_type(self) -> str:
+        """Return agent type label."""
+        return self._agent_type
+
+    @property
+    def name(self) -> str:
+        """Return configured human-readable agent name."""
+        return self._name
+
+    @property
+    def agent_instance(self) -> Any:
+        """Return compiled graph instance.
+
+        Raises:
+            RuntimeError: If the agent is not yet initialized.
+        """
+        if self._agent_instance is None:
+            raise RuntimeError("Agent not initialized. Call initialize() first.")
+        return self._agent_instance
+
+    @property
+    def configuration(self) -> HaystackAgentConfig:
+        """Return validated configuration.
+
+        Raises:
+            RuntimeError: If the agent has not been configured yet.
+        """
+        if not self._configuration:
+            raise RuntimeError("Agent not configured. Call initialize() first.")
+        return self._configuration
+
+    @property
+    def infos(self) -> dict[str, Any]:
+        """Return diagnostic information about the agent instance."""
+        return self._infos
+
+    def _check_langfuse_tracing(self, pipeline: Pipeline) -> None:
+        """Check if the pipeline has a LangfuseConnector."""
+        logger.debug("Searching LangfuseConnector in the pipeline..")
+        for name, component in pipeline.walk():
+            if isinstance(component, LangfuseConnector):
+                logger.info(f"Found LangfuseConnector component with name: {name}")
+                self._langfuse_tracing = True
+
+    def _add_langfuse_tracing(self, component: Agent | Pipeline):
+        logger.debug("Checking for Langfuse tracing...")
+        if isinstance(component, Pipeline):
+            if self._langfuse_tracing:
+                logger.info("langfuse tracing already on")
+            elif not self._langfuse_tracing and self._enable_tracing:
+                logger.info("Pipeline has no tracer included. Adding Langfuse tracer")
+                if (
+                    not os.environ.get("LANGFUSE_API_KEY")
+                    or not os.environ.get("LANGFUSE_SECRET_KEY")
+                    or not os.environ.get("LANGFUSE_PUBLIC_KEY")
+                ):
+                    raise ValueError(
+                        "Langfuse keys not set! make sure you set Langfuse secret and public keys"
+                    )
+                component.add_component(
+                    f"{self._configuration.name} tracer",
+                    instance=LangfuseConnector(self._configuration.name),
+                )
+                logger.info("Added component tracer")
+                self._langfuse_tracing = True
+        logger.info("Agent tracing not supported yet")
+
+    async def initialize(self, config: HaystackAgentConfig | dict[str, Any]) -> None:
+        try:
+            logger.debug(f"Initializing haystack agent config: {config}...")
+
+            if isinstance(config, HaystackAgentConfig):
+                self._configuration = config
+                logger.debug("Validated HaystackAgentConfig")
+            else:
+                logger.warning(f"Validating a dict config: {config}")
+                self._configuration = HaystackAgentConfig.model_validate(config)
+                logger.debug("Validated dict config")
+            self._name = self._configuration.name or "Haystack Agent"
+            self._infos["name"] = self._name
+            # TODO: await persistence haystack
+            # TODO OBS block
+
+            # check if config has observability `enabled` or `disabled`, so that we adjust our component to
+            # either add a tracer or not
+            if self._configuration.observability.enabled:
+                self._enable_tracing = True
+                logger.info("Enabling tracing...")
+            component: Agent | Pipeline = self._load_component(
+                self._configuration.component_definition
+            )
+            self._infos["component_type"] = self._configuration.component_type
+            self._infos["component_definition"] = (
+                self._configuration.component_definition
+            )
+            self._agent_instance = component
+            # TODO: input output schema definition
+            self._infos["status"] = "initialized"
+            logger.info("Status initialized!")
+            self._infos["config_used"] = self._configuration.model_dump()
+        except Exception as e:
+            logger.error(f"Failed to initialize HaystackAgent: {e}")
+            raise
+
+    def _fetch_component_from_module(self) -> Agent | Pipeline:
+        """Fetches the variable that holds the component of an Agent/Pipeline.
+
+        Returns: Agent | Pipeline.
+        """
+        module_path, component_variable_name = _parse_component_definition(
+            self._configuration.component_definition
+        )
+        logger.debug(
+            f"Importing spec from file location: {self._configuration.component_definition}"
+        )
+        try:
+            spec = importlib.util.spec_from_file_location(
+                component_variable_name, module_path
+            )
+            if spec is None or spec.loader is None:
+                logger.error(f"Could not load spec for module at {module_path}")
+                raise ImportError(f"Could not load spec for module at {module_path}")
+
+            module = importlib.util.module_from_spec(spec)
+            logger.debug("Execing module..")
+            spec.loader.exec_module(module)
+            logger.debug("Module executed")
+
+            component_variable = getattr(module, component_variable_name)
+            logger.info(f"Found component variable: {component_variable}")
+
+            component = getattr(module, component_variable_name)
+
+            if not isinstance(component, (Pipeline, Agent)):
+                raise TypeError(
+                    f"The variable '{component_variable_name}' from {module_path} is not a Pipeline or Agent instance. Got {type(component)}"
+                )
+
+            return component
+
+        except Exception as e:
+            raise ValueError(
+                f"Invalid component definition string: {self._configuration.component_definition}. Error: {e}"
+            ) from e
+
+    def _load_component(self, component_definition: str) -> Agent | Pipeline:
+        """Loads a Haystack component (Agent or Pipeline) from the path (component definition) and returns the agent_instance with langfuse tracing."""
+        logger.debug(f"Loading component from: {component_definition}...")
+
+        component = self._fetch_component_from_module()
+        if self._enable_tracing:
+            try:
+                self._add_langfuse_tracing(component)
+            except (FileNotFoundError, ImportError, AttributeError) as e:
+                raise ValueError(
+                    f"Failed to load agent from {component_definition}: {e}"
+                ) from e
+
+            return component
+        else:
+            logger.debug("User wants tracing disabled. Skipping..")
+            return component
+
+    async def invoke(self, message: Any) -> Any:
+        """Process a single input to chat with the agent.The message should be a dictionary containing 'query' and 'session_id'."""
+        # TODO: validate actual message
+        # TODO: validate input schema
+        logger.debug(f"Invoking pipeline for message: {message}")
+        if self._agent_instance is None:
+            raise RuntimeError(
+                "Agent not initialized. Call initialize() before processing messages."
+            )
+
+        if (
+            not isinstance(message, dict)
+            or "query" not in message
+            or "session_id" not in message
+        ):
+            raise ValueError(
+                "Message must be a dictionary with 'query' and 'session_id' keys."
+            )
+
+        try:
+            # TODO: support async
+            # if pipeline
+            if isinstance(self._agent_instance, Pipeline):
+                logger.debug("Running Pipeline instance...")
+                raw_result = self._agent_instance.run(data={"query": message["query"]})
+                result = raw_result["generator"]["replies"][0]
+                logger.info(f"Pipeline answer: {result}")
+                return result
+
+            # if agent
+            elif isinstance(self._agent_instance, Agent):
+                logger.debug("Running Agent instance...")
+                raw_result = self._agent_instance.run(
+                    # TODO: make run method arguments based on component type
+                    messages=[ChatMessage.from_user(message["query"])]
+                )  # TODO: from input schema
+                logger.info(f"Pipeline answer: {raw_result['messages'][-1].text}")
+                result = raw_result["messages"][-1].text
+                return result
+
+        # TODO: validates with output schema, and not hardcodded
+        except Exception as e:
+            raise RuntimeError(f"Pipeline execution failed: {e}") from e
+
+    async def stream(self, message: Any) -> Any:
+        pass

idun_agent_engine/agent/haystack/haystack_model.py

@@ -0,0 +1,13 @@
+"""Configuration models for Haystack agents."""
+
+from typing import Literal
+
+from idun_agent_engine.core.engine_config import BaseAgentConfig
+
+
+class HaystackAgentConfig(BaseAgentConfig):
+    """Configuration model for Haystack Agents."""
+
+    type: Literal["haystack"] = "haystack"
+    component_type: Literal["pipeline", "agent"]
+    component_definition: str

idun_agent_engine/agent/haystack/utils.py

@@ -0,0 +1,13 @@
+def _parse_component_definition(component_definition: str) -> tuple[str, str]:
+    try:
+        if ":" not in component_definition:
+            raise ValueError(
+                f" component_definition must be in format: 'path/to/my/module.py:component_variable_name"
+                f"got: {component_definition}"
+            )
+        module_path, component_variable_name = component_definition.rsplit(":", 1)
+        return module_path, component_variable_name
+    except Exception as e:
+        raise ValueError(
+            f"Invalid Component Definition format: {component_definition}"
+        ) from e

idun_agent_engine/agent/langgraph/__init__.py

@@ -0,0 +1,7 @@
+"""LangGraph agent package."""
+
+from .langgraph import LanggraphAgent
+
+__all__ = [
+    "LanggraphAgent",
+]