noesium 0.1.0__py3-none-any.whl

noesium/core/toolify/config.py

@@ -0,0 +1,138 @@
+"""
+Unified configuration system for noesium tools.
+"""
+
+import os
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from noesium.core.llm import get_llm_client
+
+
+class ToolkitConfig(BaseModel):
+    """
+    Unified configuration for noesium toolkits.
+
+    This configuration system supports both built-in tools and MCP integration,
+    providing a consistent interface for all toolkit types.
+    """
+
+    # Core configuration
+    mode: Literal["builtin", "mcp"] = "builtin"
+    """Toolkit mode: 'builtin' for native tools, 'mcp' for Model Context Protocol tools"""
+
+    name: Optional[str] = None
+    """Toolkit name for identification and logging"""
+
+    activated_tools: Optional[List[str]] = None
+    """List of specific tools to activate. If None, all tools are activated."""
+
+    config: Dict[str, Any] = Field(default_factory=dict)
+    """Toolkit-specific configuration parameters"""
+
+    # LLM Integration
+    llm_provider: str = Field(default_factory=lambda: os.getenv("COGENTS_LLM_PROVIDER", "openai"))
+    """LLM provider to use (openrouter, openai, ollama, llamacpp, litellm)"""
+
+    llm_model: Optional[str] = None
+    """Specific model to use for LLM operations"""
+
+    llm_config: Dict[str, Any] = Field(default_factory=dict)
+    """Additional LLM configuration parameters"""
+
+    # MCP Configuration (when mode="mcp")
+    mcp_server_path: Optional[str] = None
+    """Path to MCP server executable"""
+
+    mcp_server_args: List[str] = Field(default_factory=list)
+    """Arguments to pass to MCP server"""
+
+    mcp_server_env: Dict[str, str] = Field(default_factory=dict)
+    """Environment variables for MCP server"""
+
+    # Logging Configuration
+    log_level: str = Field(default_factory=lambda: os.getenv("LOG_LEVEL", "INFO"))
+    """Logging level for this toolkit"""
+
+    enable_tracing: bool = Field(default_factory=lambda: os.getenv("COGENTS_ENABLE_TRACING", "false").lower() == "true")
+    """Enable detailed tracing for debugging"""
+
+    class Config:
+        """Pydantic configuration"""
+
+        arbitrary_types_allowed = True
+
+    def get_llm_client(self, **kwargs):
+        """
+        Get an LLM client instance configured for this toolkit.
+
+        Args:
+            **kwargs: Additional arguments to pass to the LLM client
+
+        Returns:
+            BaseLLMClient: Configured LLM client instance
+        """
+        config = {**self.llm_config, **kwargs}
+        if self.llm_model:
+            config["chat_model"] = self.llm_model
+
+        return get_llm_client(provider=self.llm_provider, **config)
+
+    def get_tool_config(self, tool_name: str) -> Dict[str, Any]:
+        """
+        Get configuration for a specific tool.
+
+        Args:
+            tool_name: Name of the tool
+
+        Returns:
+            Dict containing tool-specific configuration
+        """
+        return self.config.get(tool_name, {})
+
+    def is_tool_activated(self, tool_name: str) -> bool:
+        """
+        Check if a specific tool is activated.
+
+        Args:
+            tool_name: Name of the tool to check
+
+        Returns:
+            True if the tool is activated, False otherwise
+        """
+        if self.activated_tools is None:
+            return True
+        return tool_name in self.activated_tools
+
+    def update_config(self, **kwargs) -> "ToolkitConfig":
+        """
+        Create a new ToolkitConfig with updated parameters.
+
+        Args:
+            **kwargs: Configuration parameters to update
+
+        Returns:
+            New ToolkitConfig instance with updated parameters
+        """
+        data = self.model_dump()
+        data.update(kwargs)
+        return ToolkitConfig(**data)
+
+
+def create_toolkit_config(
+    name: str, mode: Literal["builtin", "mcp"] = "builtin", activated_tools: Optional[List[str]] = None, **config_params
+) -> ToolkitConfig:
+    """
+    Convenience function to create a ToolkitConfig.
+
+    Args:
+        name: Toolkit name
+        mode: Toolkit mode ('builtin' or 'mcp')
+        activated_tools: List of tools to activate
+        **config_params: Additional configuration parameters
+
+    Returns:
+        Configured ToolkitConfig instance
+    """
+    return ToolkitConfig(name=name, mode=mode, activated_tools=activated_tools, config=config_params)

noesium/core/toolify/mcp_integration.py

@@ -0,0 +1,275 @@
+"""
+MCP (Model Context Protocol) integration for noesium tools.
+
+Provides functionality to run external MCP servers and integrate their tools
+into the noesium toolkit system.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from noesium.core.utils.logging import get_logger
+
+from .base import AsyncBaseToolkit, MCPNotAvailableError
+from .config import ToolkitConfig
+from .registry import register_toolkit
+
+try:
+    import mcp.client.session as mcp_session
+    import mcp.client.stdio as mcp_stdio
+    import mcp.types as mcp_types
+
+    MCP_AVAILABLE = True
+except ImportError:
+    mcp_session = None
+    mcp_stdio = None
+    mcp_types = None
+    MCP_AVAILABLE = False
+
+logger = get_logger(__name__)
+
+
+@register_toolkit("mcp")
+class MCPToolkit(AsyncBaseToolkit):
+    """
+    Toolkit for integrating external MCP (Model Context Protocol) servers.
+
+    This toolkit allows noesium to communicate with external MCP servers,
+    enabling integration with a wide variety of tools and services that
+    implement the MCP protocol.
+
+    Configuration:
+    - server_path: Path to the MCP server executable
+    - server_args: Arguments to pass to the server
+    - server_env: Environment variables for the server
+    - tools_filter: Optional list of tool names to include (if None, includes all)
+    """
+
+    def __init__(self, config: ToolkitConfig = None):
+        """
+        Initialize the MCP toolkit.
+
+        Args:
+            config: Toolkit configuration containing MCP server details
+        """
+        super().__init__(config)
+
+        if not MCP_AVAILABLE:
+            raise MCPNotAvailableError("MCP package is not available. Install with: pip install mcp")
+
+        # MCP server configuration
+        self.server_path = self.config.mcp_server_path
+        self.server_args = self.config.mcp_server_args or []
+        self.server_env = self.config.mcp_server_env or {}
+
+        if not self.server_path:
+            raise ValueError("mcp_server_path must be specified in config")
+
+        # MCP client state
+        self.session: Optional[mcp_session.ClientSession] = None
+        self.stdio_client: Optional[mcp_stdio.StdioServerParameters] = None
+        self._available_tools: Dict[str, mcp_types.Tool] = {}
+
+    async def build(self):
+        """Initialize the MCP client and connect to the server."""
+        await super().build()
+
+        if self.session is None:
+            await self._connect_to_server()
+            await self._discover_tools()
+
+    async def cleanup(self):
+        """Cleanup MCP client resources."""
+        if self.session:
+            try:
+                await self.session.close()
+            except Exception as e:
+                self.logger.warning(f"Error closing MCP session: {e}")
+
+        self.session = None
+        self.stdio_client = None
+        self._available_tools = {}
+
+        await super().cleanup()
+
+    async def _connect_to_server(self):
+        """Connect to the MCP server."""
+        try:
+            self.logger.info(f"Connecting to MCP server: {self.server_path}")
+
+            # Create stdio server parameters
+            self.stdio_client = mcp_stdio.StdioServerParameters(
+                command=self.server_path, args=self.server_args, env=self.server_env
+            )
+
+            # Create and initialize the session
+            self.session = await mcp_stdio.stdio_client(self.stdio_client)
+
+            # Initialize the session
+            await self.session.initialize()
+
+            self.logger.info("Successfully connected to MCP server")
+
+        except Exception as e:
+            self.logger.error(f"Failed to connect to MCP server: {e}")
+            raise
+
+    async def _discover_tools(self):
+        """Discover available tools from the MCP server."""
+        try:
+            if not self.session:
+                raise RuntimeError("MCP session not initialized")
+
+            # List available tools
+            tools_response = await self.session.list_tools()
+
+            self._available_tools = {}
+            for tool in tools_response.tools:
+                # Filter tools if specified in config
+                if self.config.activated_tools is None or tool.name in self.config.activated_tools:
+                    self._available_tools[tool.name] = tool
+
+            self.logger.info(f"Discovered {len(self._available_tools)} MCP tools: {list(self._available_tools.keys())}")
+
+        except Exception as e:
+            self.logger.error(f"Failed to discover MCP tools: {e}")
+            raise
+
+    async def _call_mcp_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Any:
+        """
+        Call an MCP tool with the given arguments.
+
+        Args:
+            tool_name: Name of the tool to call
+            arguments: Arguments to pass to the tool
+
+        Returns:
+            Tool execution result
+        """
+        if not self.session:
+            raise RuntimeError("MCP session not initialized")
+
+        if tool_name not in self._available_tools:
+            raise ValueError(f"Tool '{tool_name}' not available. Available tools: {list(self._available_tools.keys())}")
+
+        try:
+            self.logger.debug(f"Calling MCP tool '{tool_name}' with arguments: {arguments}")
+
+            # Call the tool
+            result = await self.session.call_tool(tool_name, arguments)
+
+            # Extract content from the result
+            if hasattr(result, "content") and result.content:
+                # Handle different content types
+                content_parts = []
+                for content in result.content:
+                    if hasattr(content, "text"):
+                        content_parts.append(content.text)
+                    elif hasattr(content, "data"):
+                        # Handle binary data
+                        content_parts.append(f"[Binary data: {len(content.data)} bytes]")
+                    else:
+                        content_parts.append(str(content))
+
+                return "\n".join(content_parts) if content_parts else str(result)
+            else:
+                return str(result)
+
+        except Exception as e:
+            self.logger.error(f"MCP tool call failed for '{tool_name}': {e}")
+            raise
+
+    async def get_tools_map(self) -> Dict[str, Any]:
+        """
+        Get the mapping of tool names to their implementation functions.
+
+        This creates wrapper functions for each MCP tool that handle the
+        argument passing and result processing.
+
+        Returns:
+            Dictionary mapping tool names to callable functions
+        """
+        tools_map = {}
+
+        for tool_name, tool_info in self._available_tools.items():
+            # Create a wrapper function for each MCP tool
+            async def tool_wrapper(tool_name=tool_name, **kwargs):
+                return await self._call_mcp_tool(tool_name, kwargs)
+
+            # Set function metadata for better introspection
+            tool_wrapper.__name__ = tool_name
+            tool_wrapper.__doc__ = tool_info.description
+
+            tools_map[tool_name] = tool_wrapper
+
+        return tools_map
+
+    async def list_available_tools(self) -> List[Dict[str, Any]]:
+        """
+        Get information about all available MCP tools.
+
+        Returns:
+            List of tool information dictionaries
+        """
+        tools_info = []
+        for tool_name, tool in self._available_tools.items():
+            info = {
+                "name": tool.name,
+                "description": tool.description,
+                "input_schema": tool.inputSchema if hasattr(tool, "inputSchema") else {},
+            }
+            tools_info.append(info)
+
+        return tools_info
+
+    async def get_tool_info(self, tool_name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get detailed information about a specific tool.
+
+        Args:
+            tool_name: Name of the tool
+
+        Returns:
+            Tool information dictionary or None if not found
+        """
+        if tool_name not in self._available_tools:
+            return None
+
+        tool = self._available_tools[tool_name]
+        return {
+            "name": tool.name,
+            "description": tool.description,
+            "input_schema": tool.inputSchema if hasattr(tool, "inputSchema") else {},
+        }
+
+
+def create_mcp_toolkit(
+    server_path: str,
+    server_args: Optional[List[str]] = None,
+    server_env: Optional[Dict[str, str]] = None,
+    activated_tools: Optional[List[str]] = None,
+    **config_params,
+) -> MCPToolkit:
+    """
+    Convenience function to create an MCP toolkit.
+
+    Args:
+        server_path: Path to the MCP server executable
+        server_args: Arguments to pass to the server
+        server_env: Environment variables for the server
+        activated_tools: List of tools to activate (None for all)
+        **config_params: Additional configuration parameters
+
+    Returns:
+        Configured MCPToolkit instance
+    """
+    config = ToolkitConfig(
+        mode="mcp",
+        name="mcp",
+        activated_tools=activated_tools,
+        mcp_server_path=server_path,
+        mcp_server_args=server_args or [],
+        mcp_server_env=server_env or {},
+        config=config_params,
+    )
+
+    return MCPToolkit(config=config)

noesium/core/toolify/registry.py

@@ -0,0 +1,214 @@
+"""
+Toolkit registry for managing and discovering available toolkits.
+"""
+
+from typing import Dict, List, Optional, Type, Union
+
+from noesium.core.utils.logging import get_logger
+
+from .base import AsyncBaseToolkit, BaseToolkit
+from .config import ToolkitConfig
+
+logger = get_logger(__name__)
+
+
+class ToolkitRegistry:
+    """
+    Registry for managing available toolkits.
+
+    Provides a centralized way to register, discover, and instantiate toolkits.
+    """
+
+    _registry: Dict[str, Type[Union[BaseToolkit, AsyncBaseToolkit]]] = {}
+
+    @classmethod
+    def register(cls, name: str, toolkit_class: Type[Union[BaseToolkit, AsyncBaseToolkit]]):
+        """
+        Register a toolkit class.
+
+        Args:
+            name: Toolkit name for lookup
+            toolkit_class: Toolkit class to register
+        """
+        if not issubclass(toolkit_class, (BaseToolkit, AsyncBaseToolkit)):
+            raise ValueError(f"Toolkit class must inherit from BaseToolkit or AsyncBaseToolkit")
+
+        cls._registry[name] = toolkit_class
+        logger.debug(f"Registered toolkit: {name} -> {toolkit_class.__name__}")
+
+    @classmethod
+    def unregister(cls, name: str):
+        """
+        Unregister a toolkit.
+
+        Args:
+            name: Toolkit name to unregister
+        """
+        if name in cls._registry:
+            del cls._registry[name]
+            logger.debug(f"Unregistered toolkit: {name}")
+
+    @classmethod
+    def get_toolkit_class(cls, name: str) -> Type[Union[BaseToolkit, AsyncBaseToolkit]]:
+        """
+        Get a registered toolkit class by name.
+
+        Args:
+            name: Toolkit name
+
+        Returns:
+            Toolkit class
+
+        Raises:
+            KeyError: If toolkit is not registered
+        """
+        if name not in cls._registry:
+            raise KeyError(f"Toolkit '{name}' not found. Available toolkits: {list(cls._registry.keys())}")
+        return cls._registry[name]
+
+    @classmethod
+    def list_toolkits(cls) -> List[str]:
+        """
+        Get list of registered toolkit names.
+
+        Returns:
+            List of toolkit names
+        """
+        return list(cls._registry.keys())
+
+    @classmethod
+    def create_toolkit(
+        cls, name: str, config: Optional[Union[ToolkitConfig, Dict]] = None
+    ) -> Union[BaseToolkit, AsyncBaseToolkit]:
+        """
+        Create a toolkit instance by name.
+
+        Args:
+            name: Toolkit name
+            config: Toolkit configuration
+
+        Returns:
+            Toolkit instance
+
+        Raises:
+            KeyError: If toolkit is not registered
+        """
+        toolkit_class = cls.get_toolkit_class(name)
+        return toolkit_class(config=config)
+
+    @classmethod
+    def is_registered(cls, name: str) -> bool:
+        """
+        Check if a toolkit is registered.
+
+        Args:
+            name: Toolkit name
+
+        Returns:
+            True if registered, False otherwise
+        """
+        return name in cls._registry
+
+    @classmethod
+    def clear(cls):
+        """Clear all registered toolkits."""
+        cls._registry.clear()
+        logger.debug("Cleared toolkit registry")
+
+
+def register_toolkit(name: str):
+    """
+    Decorator for registering toolkit classes.
+
+    Args:
+        name: Toolkit name for registration
+
+    Example:
+        @register_toolkit("search")
+        class SearchToolkit(AsyncBaseToolkit):
+            pass
+    """
+
+    def decorator(toolkit_class: Type[Union[BaseToolkit, AsyncBaseToolkit]]):
+        ToolkitRegistry.register(name, toolkit_class)
+        return toolkit_class
+
+    return decorator
+
+
+def get_toolkit(name: str, config: Optional[Union[ToolkitConfig, Dict]] = None) -> Union[BaseToolkit, AsyncBaseToolkit]:
+    """
+    Convenience function to get a toolkit instance.
+
+    Args:
+        name: Toolkit name
+        config: Toolkit configuration
+
+    Returns:
+        Toolkit instance
+    """
+    return ToolkitRegistry.create_toolkit(name, config)
+
+
+def get_toolkits_map(
+    names: Optional[List[str]] = None, configs: Optional[Dict[str, Union[ToolkitConfig, Dict]]] = None
+) -> Dict[str, Union[BaseToolkit, AsyncBaseToolkit]]:
+    """
+    Get multiple toolkit instances as a mapping.
+
+    Args:
+        names: List of toolkit names (if None, gets all registered toolkits)
+        configs: Mapping of toolkit names to their configurations
+
+    Returns:
+        Dict mapping toolkit names to instances
+    """
+    if names is None:
+        names = ToolkitRegistry.list_toolkits()
+
+    if configs is None:
+        configs = {}
+
+    toolkits = {}
+    for name in names:
+        config = configs.get(name)
+        toolkits[name] = ToolkitRegistry.create_toolkit(name, config)
+
+    return toolkits
+
+
+# Auto-discovery of built-in toolkits
+def _discover_builtin_toolkits():
+    """
+    Discover and register built-in toolkits.
+
+    This function attempts to import and register all built-in toolkit modules.
+    """
+    import importlib
+    import pkgutil
+    from pathlib import Path
+
+    # Get the toolkits directory
+    toolkits_dir = Path(__file__).parent / "toolkits"
+
+    if not toolkits_dir.exists():
+        return
+
+    # Import all toolkit modules
+    for module_info in pkgutil.iter_modules([str(toolkits_dir)]):
+        if module_info.name.startswith("_"):
+            continue
+
+        try:
+            module_name = f"noesium.core.toolify.toolkits.{module_info.name}"
+            importlib.import_module(module_name)
+            logger.debug(f"Discovered toolkit module: {module_name}")
+        except ImportError as e:
+            logger.warning(f"Failed to import toolkit module {module_name}: {e}")
+
+
+# Initialize built-in toolkits on import
+try:
+    _discover_builtin_toolkits()
+except Exception as e:
+    logger.warning(f"Failed to discover built-in toolkits: {e}")

noesium/core/toolify/toolkits/__init__.py

@@ -0,0 +1 @@
+# Core built-in toolkits

noesium/core/tracing/__init__.py

@@ -0,0 +1,37 @@
+"""
+Tracing and observability modules for the noesium framework.
+
+This package provides:
+- Opik tracing configuration for LLM communications
+- Token usage tracking for custom LLM clients
+- LangGraph hooks and callbacks for monitoring
+"""
+
+from .langgraph_hooks import NodeLoggingCallback, TokenUsageCallback
+from .opik_tracing import configure_opik, create_opik_trace, get_opik_project, is_opik_enabled
+from .token_tracker import (
+    TokenUsage,
+    TokenUsageTracker,
+    estimate_token_usage,
+    extract_token_usage_from_openai_response,
+    get_token_tracker,
+    record_token_usage,
+)
+
+__all__ = [
+    # LangGraph hooks
+    "NodeLoggingCallback",
+    "TokenUsageCallback",
+    # Opik tracing
+    "configure_opik",
+    "create_opik_trace",
+    "get_opik_project",
+    "is_opik_enabled",
+    # Token tracking
+    "TokenUsage",
+    "TokenUsageTracker",
+    "estimate_token_usage",
+    "extract_token_usage_from_openai_response",
+    "get_token_tracker",
+    "record_token_usage",
+]