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

idun_agent_engine/core/config_builder.py

@@ -0,0 +1,456 @@
+"""Configuration Builder for Idun Agent Engine.
+
+This module provides a fluent API for building configuration objects using Pydantic models.
+This approach ensures type safety, validation, and consistency with the rest of the codebase.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from idun_agent_schema.engine.agent_framework import AgentFramework
+from idun_agent_schema.engine.haystack import HaystackAgentConfig
+from idun_agent_schema.engine.langgraph import (
+    LangGraphAgentConfig,
+    SqliteCheckpointConfig,
+)
+
+from idun_agent_engine.server.server_config import ServerAPIConfig
+
+from ..agent.base import BaseAgent
+from .engine_config import AgentConfig, EngineConfig, ServerConfig
+
+
+class ConfigBuilder:
+    """A fluent builder for creating Idun Agent Engine configurations using Pydantic models.
+
+    This class provides a convenient way to build strongly-typed configuration objects
+    that are validated at creation time, ensuring consistency and catching errors early.
+    It also handles agent initialization and management.
+
+    Example:
+        config = (ConfigBuilder()
+                 .with_api_port(8080)
+                 .with_langgraph_agent(
+                     name="My Agent",
+                     graph_definition="my_agent.py:graph",
+                     sqlite_checkpointer="agent.db")
+                 .build())
+
+        app = create_app(config_dict=config.model_dump())
+    """
+
+    def __init__(self):
+        """Initialize a new configuration builder with default values."""
+        self._server_config = ServerConfig()
+        self._agent_config: AgentConfig | None = None
+
+    def with_api_port(self, port: int) -> "ConfigBuilder":
+        """Set the API port for the server.
+
+        Args:
+            port: The port number to bind the server to
+
+        Returns:
+            ConfigBuilder: This builder instance for method chaining
+        """
+        # Create new API config with updated port
+        api_config = ServerAPIConfig(port=port)
+        self._server_config = ServerConfig(
+            api=api_config,
+        )
+        return self
+
+    def with_server_config(
+        self, api_port: int | None = None, telemetry_provider: str | None = None
+    ) -> "ConfigBuilder":
+        """Set server configuration options directly.
+
+        Args:
+            api_port: Optional API port
+            telemetry_provider: Optional telemetry provider
+
+        Returns:
+            ConfigBuilder: This builder instance for method chaining
+        """
+        api_config = (
+            ServerAPIConfig(port=api_port) if api_port else self._server_config.api
+        )
+
+        self._server_config = ServerConfig(api=api_config)
+        return self
+
+    def with_config_from_api(self, agent_api_key: str, url: str) -> "ConfigBuilder":
+        """Fetches the yaml config file, from idun agent manager api.
+
+        Requires the agent api key to pass in the headers.
+        """
+        import requests
+        import yaml
+
+        headers = {"auth": f"Bearer {agent_api_key}"}
+        try:
+            response = requests.get(url=url, headers=headers)
+            if response.status_code != 200:
+                raise ValueError(
+                    f"Error sending retrieving config from url. response : {response.json()}"
+                )
+            yaml_config = yaml.safe_load(response.text)
+            self._server_config = yaml_config["engine_config"]["server"]
+            self._agent_config = yaml_config["engine_config"]["agent"]
+            return self
+
+        except Exception as e:
+            raise ValueError(f"Error occured while getting config from api: {e}") from e
+
+    def with_langgraph_agent(
+        self,
+        name: str,
+        graph_definition: str,
+        sqlite_checkpointer: str | None = None,
+        **additional_config,
+    ) -> "ConfigBuilder":
+        """Configure a LangGraph agent using the LangGraphAgentConfig model.
+
+        Args:
+            name: Human-readable name for the agent
+            graph_definition: Path to the graph in format "module.py:variable_name"
+            sqlite_checkpointer: Optional path to SQLite database for checkpointing
+            **additional_config: Additional configuration parameters
+
+        Returns:
+            ConfigBuilder: This builder instance for method chaining
+        """
+        # Build the agent config dictionary
+        agent_config_dict = {
+            "name": name,
+            "graph_definition": graph_definition,
+            **additional_config,
+        }
+
+        # Add checkpointer if specified
+        if sqlite_checkpointer:
+            checkpointer = SqliteCheckpointConfig(
+                type="sqlite", db_url=f"sqlite:///{sqlite_checkpointer}"
+            )
+            agent_config_dict["checkpointer"] = checkpointer
+
+        # Create and validate the LangGraph config
+        langgraph_config = LangGraphAgentConfig.model_validate(agent_config_dict)
+
+        # Create the agent config (store as strongly-typed model, not dict)
+        self._agent_config = AgentConfig(type="langgraph", config=langgraph_config)
+        return self
+
+    def with_custom_agent(
+        self, agent_type: str, config: dict[str, Any]
+    ) -> "ConfigBuilder":
+        """Configure a custom agent type.
+
+        This method allows for configuring agent types that don't have
+        dedicated builder methods yet. The config will be validated
+        when the AgentConfig is created.
+
+        Args:
+            agent_type: The type of agent (e.g., "crewai", "autogen")
+            config: Configuration dictionary specific to the agent type
+
+        Returns:
+            ConfigBuilder: This builder instance for method chaining
+        """
+        if agent_type == AgentFramework.LANGGRAPH:
+            self._agent_config = AgentConfig(
+                type="langgraph", config=LangGraphAgentConfig.model_validate(config)
+            )
+
+        elif agent_type == AgentFramework.HAYSTACK:
+            self._agent_config = AgentConfig(
+                type="haystack", config=HaystackAgentConfig.model_validate(config)
+            )
+        else:
+            raise ValueError(f"Unsupported agent type: {agent_type}")
+        return self
+
+    def build(self) -> EngineConfig:
+        """Build and return the complete configuration as a validated Pydantic model.
+
+        Returns:
+            EngineConfig: The complete, validated configuration object
+
+        Raises:
+            ValueError: If the configuration is incomplete or invalid
+        """
+        if not self._agent_config:
+            raise ValueError(
+                "Agent configuration is required. Use with_langgraph_agent() or with_custom_agent()"
+            )
+
+        # Create and validate the complete configuration
+        return EngineConfig(server=self._server_config, agent=self._agent_config)
+
+    def build_dict(self) -> dict[str, Any]:
+        """Build and return the configuration as a dictionary.
+
+        This is a convenience method for backward compatibility.
+
+        Returns:
+            Dict[str, Any]: The complete configuration dictionary
+        """
+        engine_config = self.build()
+        return engine_config.model_dump()
+
+    def save_to_file(self, file_path: str) -> None:
+        """Save the configuration to a YAML file.
+
+        Args:
+            file_path: Path where to save the configuration file
+        """
+        config = self.build_dict()
+        with open(file_path, "w") as f:
+            yaml.dump(config, f, default_flow_style=False, indent=2)
+
+    async def build_and_initialize_agent(self) -> BaseAgent:
+        """Build configuration and initialize the agent in one step.
+
+        Returns:
+            BaseAgent: Initialized agent instance
+
+        Raises:
+            ValueError: If agent type is unsupported or configuration is invalid
+        """
+        engine_config = self.build()
+        return await self.initialize_agent_from_config(engine_config)
+
+    @staticmethod
+    async def initialize_agent_from_config(engine_config: EngineConfig) -> BaseAgent:
+        """Initialize an agent instance from a validated EngineConfig.
+
+        Args:
+            engine_config: Validated configuration object
+
+        Returns:
+            BaseAgent: Initialized agent instance
+
+        Raises:
+            ValueError: If agent type is unsupported
+        """
+        agent_config_obj = engine_config.agent.config
+        print("CONFIG:", agent_config_obj)
+        agent_type = engine_config.agent.type
+
+        # Initialize the appropriate agent
+        agent_instance = None
+        if agent_type == AgentFramework.LANGGRAPH:
+            from idun_agent_engine.agent.langgraph.langgraph import LanggraphAgent
+
+            try:
+                validated_config = LangGraphAgentConfig.model_validate(agent_config_obj)
+
+            except Exception as e:
+                raise ValueError(
+                    f"Cannot validate into a LangGraphAgentConfig model. Got {agent_config_obj}"
+                ) from e
+
+            agent_instance = LanggraphAgent()
+
+        elif agent_type == AgentFramework.HAYSTACK:
+            from idun_agent_engine.agent.haystack.haystack import HaystackAgent
+
+            try:
+                validated_config = HaystackAgentConfig.model_validate(agent_config_obj)
+
+            except Exception as e:
+                raise ValueError(
+                    f"Cannot validate into a HaystackAgentConfig model. Got {agent_config_obj}"
+                ) from e
+            agent_instance = HaystackAgent()
+        else:
+            raise ValueError(f"Unsupported agent type: {agent_type}")
+
+        # Initialize the agent with its configuration
+        await agent_instance.initialize(validated_config)  # type: ignore[arg-type]
+        return agent_instance
+
+    @staticmethod
+    def get_agent_class(agent_type: str) -> type[BaseAgent]:
+        """Get the agent class for a given agent type without initializing it.
+
+        Args:
+            agent_type: The type of agent
+
+        Returns:
+            Type[BaseAgent]: The agent class
+
+        Raises:
+            ValueError: If agent type is unsupported
+        """
+        if agent_type == "langgraph":
+            from ..agent.langgraph.langgraph import LanggraphAgent
+
+            return LanggraphAgent
+
+        else:
+            raise ValueError(f"Unsupported agent type: {agent_type}")
+
+    @staticmethod
+    def validate_agent_config(
+        agent_type: str, config: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Validate agent configuration against the appropriate Pydantic model.
+
+        Args:
+            agent_type: The type of agent
+            config: Configuration dictionary to validate
+
+        Returns:
+            Dict[str, Any]: Validated configuration dictionary
+
+        Raises:
+            ValueError: If agent type is unsupported or config is invalid
+        """
+        if agent_type == "langgraph":
+            validated_config = LangGraphAgentConfig.model_validate(config)
+            return validated_config.model_dump()
+        # Future agent types can be added here:
+        # elif agent_type == "crewai":
+        #     validated_config = CrewAIAgentConfig.model_validate(config)
+        #     return validated_config.model_dump()
+        else:
+            raise ValueError(f"Unsupported agent type: {agent_type}")
+
+    @staticmethod
+    def load_from_file(config_path: str = "config.yaml") -> EngineConfig:
+        """Load configuration from a YAML file and return a validated EngineConfig.
+
+        Args:
+            config_path: Path to the configuration YAML file
+
+        Returns:
+            EngineConfig: Validated configuration object
+
+        Raises:
+            FileNotFoundError: If the configuration file doesn't exist
+            ValidationError: If the configuration is invalid
+        """
+        path = Path(config_path)
+        if not path.is_absolute():
+            # Resolve relative to the current working directory
+            path = Path.cwd() / path
+
+        with open(path) as f:
+            config_data = yaml.safe_load(f)
+
+        return EngineConfig.model_validate(config_data)
+
+    @staticmethod
+    async def load_and_initialize_agent(
+        config_path: str = "config.yaml",
+    ) -> tuple[EngineConfig, BaseAgent]:
+        """Load configuration and initialize agent in one step.
+
+        Args:
+            config_path: Path to the configuration YAML file
+
+        Returns:
+            tuple[EngineConfig, BaseAgent]: Configuration and initialized agent
+        """
+        engine_config = ConfigBuilder.load_from_file(config_path)
+        agent = await ConfigBuilder.initialize_agent_from_config(engine_config)
+        return engine_config, agent
+
+    @staticmethod
+    def resolve_config(
+        config_path: str | None = None,
+        config_dict: dict[str, Any] | None = None,
+        engine_config: EngineConfig | None = None,
+    ) -> EngineConfig:
+        """Umbrella function to resolve configuration from various sources.
+
+        This function handles all the different ways configuration can be provided
+        and returns a validated EngineConfig. It follows a priority order:
+        1. engine_config (pre-validated EngineConfig from ConfigBuilder)
+        2. config_dict (dictionary to be validated)
+        3. config_path (file path to load and validate)
+        4. default "config.yaml" file
+
+        Args:
+            config_path: Path to a YAML configuration file
+            config_dict: Dictionary containing configuration
+            engine_config: Pre-validated EngineConfig instance
+
+        Returns:
+            EngineConfig: Validated configuration object
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValidationError: If configuration is invalid
+        """
+        if engine_config:
+            # Use pre-validated EngineConfig (from ConfigBuilder)
+            print("✅ Using pre-validated EngineConfig")
+            return engine_config
+        elif config_dict:
+            # Validate dictionary config
+            print("✅ Validated dictionary configuration")
+            return EngineConfig.model_validate(config_dict)
+        elif config_path:
+            # Load from file using ConfigB/uilder
+            print(f"✅ Loaded configuration from {config_path}")
+            return ConfigBuilder.load_from_file(config_path)
+        else:
+            # Default to loading config.yaml
+            print("✅ Loaded default configuration from config.yaml")
+            return ConfigBuilder.load_from_file("config.yaml")
+
+    @classmethod
+    def from_dict(cls, config_dict: dict[str, Any]) -> "ConfigBuilder":
+        """Create a ConfigBuilder from an existing configuration dictionary.
+
+        This method validates the input dictionary against the Pydantic models.
+
+        Args:
+            config_dict: Existing configuration dictionary
+
+        Returns:
+            ConfigBuilder: A new builder instance with the provided configuration
+
+        Raises:
+            ValidationError: If the configuration dictionary is invalid
+        """
+        # Validate the entire config first
+        engine_config = EngineConfig.model_validate(config_dict)
+
+        # Create a new builder
+        builder = cls()
+        builder._server_config = engine_config.server
+        builder._agent_config = engine_config.agent
+
+        return builder
+
+    @classmethod
+    def from_file(cls, config_path: str = "config.yaml") -> "ConfigBuilder":
+        """Create a ConfigBuilder from a YAML configuration file.
+
+        Args:
+            config_path: Path to the configuration YAML file
+
+        Returns:
+            ConfigBuilder: A new builder instance with the loaded configuration
+        """
+        engine_config = cls.load_from_file(config_path)
+        return cls.from_engine_config(engine_config)
+
+    @classmethod
+    def from_engine_config(cls, engine_config: EngineConfig) -> "ConfigBuilder":
+        """Create a ConfigBuilder from an existing EngineConfig instance.
+
+        Args:
+            engine_config: Existing EngineConfig instance
+
+        Returns:
+            ConfigBuilder: A new builder instance with the provided configuration
+        """
+        builder = cls()
+        builder._server_config = engine_config.server
+        builder._agent_config = engine_config.agent
+        return builder

idun_agent_engine/core/engine_config.py

@@ -0,0 +1,22 @@
+"""Compatibility re-exports for Engine configuration models."""
+
+from idun_agent_schema.engine.agent import BaseAgentConfig  # noqa: F401
+from idun_agent_schema.engine.agent import (  # noqa: F401
+    AgentConfig,
+)
+
+from idun_agent_schema.engine.engine import (  # noqa: F401
+    EngineConfig,
+)
+from idun_agent_schema.engine.langgraph import (  # noqa: F401
+    LangGraphAgentConfig,
+)
+from idun_agent_schema.engine.server import ServerConfig  # noqa: F401
+
+__all__ = [
+    "AgentConfig",
+    "EngineConfig",
+    "LangGraphAgentConfig",
+    "BaseAgentConfig",
+    "ServerConfig",
+]

idun_agent_engine/core/server_runner.py

@@ -0,0 +1,146 @@
+"""Server Runner for Idun Agent Engine.
+
+This module provides convenient functions to run FastAPI applications created with
+the Idun Agent Engine. It handles common deployment scenarios and provides sensible defaults.
+"""
+
+import uvicorn
+from fastapi import FastAPI
+
+
+def run_server(
+    app: FastAPI,
+    host: str = "0.0.0.0",
+    port: int = 8000,
+    reload: bool = False,
+    log_level: str = "info",
+    workers: int | None = None,
+) -> None:
+    """Run a FastAPI application created with Idun Agent Engine.
+
+    This is a convenience function that wraps uvicorn.run() with sensible defaults
+    for serving agent applications. It automatically handles common deployment scenarios.
+
+    Args:
+        app: The FastAPI application created with create_app()
+        host: Host to bind the server to. Defaults to "0.0.0.0" (all interfaces)
+        port: Port to bind the server to. Defaults to 8000
+        reload: Enable auto-reload for development. Defaults to False
+        log_level: Logging level. Defaults to "info"
+        workers: Number of worker processes. If None, uses single process
+
+    Example:
+        from idun_agent_engine import create_app, run_server
+
+        # Create your app
+        app = create_app("config.yaml")
+
+        # Run in development mode
+        run_server(app, reload=True)
+
+        # Run in production mode
+        run_server(app, workers=4)
+    """
+    print(f"🌐 Starting Idun Agent Engine server on http://{host}:{port}")
+    print(f"📚 API documentation available at http://{host}:{port}/docs")
+
+    if reload and workers:
+        print(
+            "⚠️  Warning: reload=True is incompatible with workers > 1. Disabling reload."
+        )
+        reload = False
+
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        # reload=reload,
+        log_level=log_level,
+        # workers=workers
+    )
+
+
+def run_server_from_config(config_path: str = "config.yaml", **kwargs) -> None:
+    """Create and run a server directly from a configuration file.
+
+    This is the most convenient way to start a server - it combines create_app()
+    and run_server() in a single function call using ConfigBuilder.
+
+    Args:
+        config_path: Path to the configuration YAML file
+        **kwargs: Additional arguments passed to run_server()
+
+    Example:
+        # Run server directly from config
+        run_server_from_config("my_agent.yaml", port=8080, reload=True)
+    """
+    from .app_factory import create_app
+    from .config_builder import ConfigBuilder
+
+    # Load configuration using ConfigBuilder
+    engine_config = ConfigBuilder.load_from_file(config_path)
+
+    # Create app with the loaded config
+    app = create_app(engine_config=engine_config)
+
+    # Extract port from config if not overridden
+    if "port" not in kwargs:
+        kwargs["port"] = engine_config.server.api.port
+
+    # Show configuration info
+    print(f"🔧 Loaded configuration from {config_path}")
+    # Best-effort: handle both dict-like and model access
+    agent_name = (
+        engine_config.agent.config.get("name")  # type: ignore[call-arg, index]
+        if hasattr(engine_config.agent.config, "get")
+        else getattr(engine_config.agent.config, "name", "Unknown")
+    )
+    print(f"🤖 Agent: {agent_name} ({engine_config.agent.type})")
+
+    run_server(app, **kwargs)
+
+
+def run_server_from_builder(config_builder, **kwargs) -> None:
+    """Create and run a server directly from a ConfigBuilder instance.
+
+    This allows for programmatic configuration with immediate server startup.
+
+    Args:
+        config_builder: ConfigBuilder instance (can be built or unbuilt)
+        **kwargs: Additional arguments passed to run_server()
+
+    Example:
+        from idun_agent_engine import ConfigBuilder
+
+        builder = (ConfigBuilder()
+                  .with_langgraph_agent(name="My Agent", graph_definition="agent.py:graph")
+                  .with_api_port(8080))
+
+        run_server_from_builder(builder, reload=True)
+    """
+    from .app_factory import create_app
+
+    # Build the configuration if it's a ConfigBuilder instance
+    if hasattr(config_builder, "build"):
+        engine_config = config_builder.build()
+    else:
+        # Assume it's already an EngineConfig
+        engine_config = config_builder
+
+    # Create app with the config
+    app = create_app(engine_config=engine_config)
+
+    # Extract port from config if not overridden
+    if "port" not in kwargs:
+        kwargs["port"] = engine_config.server.api.port
+
+    # Show configuration info
+    print("🔧 Using programmatic configuration")
+    agent_name = (
+        engine_config.agent.config.get("name")  # type: ignore[call-arg, index]
+        if hasattr(engine_config.agent.config, "get")
+        else getattr(engine_config.agent.config, "name", "Unknown")
+    )
+    print(f"🤖 Agent: {agent_name} ({engine_config.agent.type})")
+
+    run_server(app, **kwargs)

idun_agent_engine/observability/__init__.py

@@ -0,0 +1,13 @@
+"""Observability package providing provider-agnostic tracing interfaces."""
+
+from .base import (
+    ObservabilityConfig,
+    ObservabilityHandlerBase,
+    create_observability_handler,
+)
+
+__all__ = [
+    "ObservabilityConfig",
+    "ObservabilityHandlerBase",
+    "create_observability_handler",
+]