noesium 0.1.0__py3-none-any.whl

noesium/core/routing/strategies/self_assessment.py

@@ -0,0 +1,147 @@
+"""Self-assessment routing strategy implementation."""
+
+from noesium.core.routing.base import BaseRoutingStrategy
+from noesium.core.routing.types import ComplexityScore, ModelTier, RoutingResult
+from noesium.core.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class SelfAssessmentStrategy(BaseRoutingStrategy):
+    """
+    Routing strategy where the lite model assesses query complexity itself.
+
+    This strategy asks the lite model to rate the complexity of a query
+    and routes based on that self-assessment.
+    """
+
+    def __init__(self, lite_client=None, config=None):
+        """
+        Initialize the self-assessment strategy.
+
+        Args:
+            lite_client: LLM client for the lite model
+            config: Configuration dict with optional parameters:
+                - temperature: Temperature for lite model (default: 0.1)
+                - max_tokens: Max tokens for assessment (default: 5)
+                - lite_threshold: Max score for lite routing (default: 1)
+                - fast_threshold: Max score for fast routing (default: 3)
+        """
+        super().__init__(lite_client, config)
+
+        if not self.lite_client:
+            raise ValueError("SelfAssessmentStrategy requires a lite_client")
+
+        # Configuration parameters
+        self.temperature = self.config.get("temperature", 0.1)
+        self.max_tokens = self.config.get("max_tokens", 5)
+        self.lite_threshold = self.config.get("lite_threshold", 1)
+        self.fast_threshold = self.config.get("fast_threshold", 3)
+
+    def route(self, query: str) -> RoutingResult:
+        """
+        Route query based on lite model's self-assessment.
+
+        Args:
+            query: Input query to assess
+
+        Returns:
+            RoutingResult with tier recommendation
+        """
+        try:
+            # Create assessment prompt
+            prompt = self._create_assessment_prompt(query)
+            messages = [{"role": "user", "content": prompt}]
+
+            # Get assessment from lite model
+            response = self.lite_client.completion(
+                messages=messages, temperature=self.temperature, max_tokens=self.max_tokens
+            )
+
+            # Parse complexity score
+            complexity_score, confidence = self._parse_assessment_response(response)
+
+            # Determine tier based on score
+            tier = self._score_to_tier(complexity_score)
+
+            # Create complexity score object
+            score_obj = ComplexityScore(
+                total=complexity_score / 5.0,  # Normalize to 0-1 range
+                metadata={"raw_score": complexity_score, "raw_response": response},
+            )
+
+            return self._create_result(
+                tier=tier, confidence=confidence, complexity_score=score_obj, metadata={"raw_assessment": response}
+            )
+
+        except Exception as e:
+            logger.error(f"Error in self-assessment routing: {e}")
+            # Fallback to fast tier on error
+            return self._create_result(
+                tier=ModelTier.FAST,
+                confidence=0.0,
+                complexity_score=ComplexityScore(total=0.5),
+                metadata={"error": str(e), "fallback": True},
+            )
+
+    def get_strategy_name(self) -> str:
+        """Return the strategy name."""
+        return "self_assessment"
+
+    def _create_assessment_prompt(self, query: str) -> str:
+        """Create the assessment prompt for the lite model."""
+        return f"""You are a request classifier. Rate the complexity of the following request:
+- 1 = simple fact or direct instruction (lite model can handle)
+- 2-3 = reasoning or multi-sentence but not too complex (fast model recommended)
+- 4-5 = deep reasoning, creativity, or novel synthesis (power model required)
+
+Request: "{query}"
+
+Output ONLY a number from 1 to 5:"""
+
+    def _parse_assessment_response(self, response: str) -> tuple[int, float]:
+        """
+        Parse the assessment response to extract complexity score.
+
+        Args:
+            response: Raw response from lite model
+
+        Returns:
+            Tuple of (complexity_score, confidence)
+        """
+        try:
+            # Extract first digit from response
+            response_clean = response.strip()
+            for char in response_clean:
+                if char.isdigit():
+                    score = int(char)
+                    if 1 <= score <= 5:
+                        # Higher confidence if response is clean (just the number with no extra text)
+                        is_clean = response_clean.strip() == str(score)
+                        confidence = 0.9 if is_clean else 0.7
+                        return score, confidence
+
+            # Fallback if no valid digit found
+            logger.warning(f"Could not parse assessment response: {response}")
+            return 3, 0.3  # Default to medium complexity with low confidence
+
+        except Exception as e:
+            logger.error(f"Error parsing assessment response: {e}")
+            return 3, 0.1
+
+    def _score_to_tier(self, score: int) -> ModelTier:
+        """
+        Convert complexity score to model tier.
+
+        Args:
+            score: Complexity score from 1-5
+
+        Returns:
+            Appropriate ModelTier
+        """
+        if score <= self.lite_threshold:
+            return ModelTier.LITE
+        elif score <= self.fast_threshold:
+            return ModelTier.FAST
+        else:
+            return ModelTier.POWER

noesium/core/routing/types.py

@@ -0,0 +1,38 @@
+"""Type definitions and enums for the routing module."""
+
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelTier(str, Enum):
+    """Enumeration of model tiers based on capability and resource requirements."""
+
+    LITE = "lite"  # Fast, low-resource models for simple tasks
+    FAST = "fast"  # Balanced models for moderate complexity
+    POWER = "power"  # High-capability models for complex reasoning
+
+
+class ComplexityScore(BaseModel):
+    """Represents a complexity score with breakdown of different factors."""
+
+    total: float = Field(..., ge=0.0, le=1.0, description="Overall complexity score (0.0-1.0)")
+    linguistic: Optional[float] = Field(None, ge=0.0, le=1.0, description="Linguistic complexity component")
+    reasoning: Optional[float] = Field(None, ge=0.0, le=1.0, description="Reasoning depth component")
+    uncertainty: Optional[float] = Field(None, ge=0.0, le=1.0, description="Knowledge uncertainty component")
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Additional metadata")
+
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+
+class RoutingResult(BaseModel):
+    """Result of a routing decision."""
+
+    tier: ModelTier = Field(..., description="Recommended model tier")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="Confidence in the routing decision (0.0-1.0)")
+    complexity_score: ComplexityScore = Field(..., description="Detailed complexity breakdown")
+    strategy: str = Field(..., description="Name of the strategy used")
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Additional routing metadata")
+
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)

noesium/core/toolify/__init__.py

@@ -0,0 +1,39 @@
+"""
+Noesium Tools Module
+
+A unified toolkit system for LLM-based agents with support for:
+- LangChain tool integration
+- MCP (Model Context Protocol) support
+- Unified configuration management
+- Built-in logging and LLM integration
+"""
+
+from .base import AsyncBaseToolkit, BaseToolkit
+from .config import ToolkitConfig
+from .registry import ToolkitRegistry, get_toolkit, get_toolkits_map
+
+# Import MCP integration if available
+try:
+    MCP_AVAILABLE = True
+    __all__ = [
+        "ToolkitConfig",
+        "BaseToolkit",
+        "AsyncBaseToolkit",
+        "ToolkitRegistry",
+        "get_toolkit",
+        "get_toolkits_map",
+        "MCPToolkit",
+        "create_mcp_toolkit",
+        "MCP_AVAILABLE",
+    ]
+except ImportError:
+    MCP_AVAILABLE = False
+    __all__ = [
+        "ToolkitConfig",
+        "BaseToolkit",
+        "AsyncBaseToolkit",
+        "ToolkitRegistry",
+        "get_toolkit",
+        "get_toolkits_map",
+        "MCP_AVAILABLE",
+    ]

noesium/core/toolify/base.py

@@ -0,0 +1,360 @@
+"""
+Base toolkit classes for noesium tools system.
+
+Provides abstract base classes for both synchronous and asynchronous toolkits
+with support for LangChain tools, MCP integration, and unified configuration.
+"""
+
+import abc
+import asyncio
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from langchain_core.tools import BaseTool, tool
+
+from noesium.core.llm import BaseLLMClient
+from noesium.core.utils.logging import get_logger
+
+from .config import ToolkitConfig
+
+try:
+    import mcp.types as mcp_types
+
+    MCP_AVAILABLE = True
+except ImportError:
+    mcp_types = None
+    MCP_AVAILABLE = False
+
+
+class ToolkitError(Exception):
+    """Base exception for toolkit-related errors."""
+
+
+class MCPNotAvailableError(ToolkitError):
+    """Raised when MCP functionality is requested but not available."""
+
+
+class ToolConverter:
+    """Utility class for converting between different tool formats."""
+
+    @staticmethod
+    def langchain_to_mcp(langchain_tool: BaseTool) -> "mcp_types.Tool":
+        """
+        Convert a LangChain tool to MCP format.
+
+        Args:
+            langchain_tool: LangChain BaseTool instance
+
+        Returns:
+            MCP Tool instance
+
+        Raises:
+            MCPNotAvailableError: If MCP is not available
+        """
+        if not MCP_AVAILABLE:
+            raise MCPNotAvailableError("MCP package is not installed")
+
+        return mcp_types.Tool(
+            name=langchain_tool.name,
+            description=langchain_tool.description,
+            inputSchema=langchain_tool.args_schema.model_json_schema() if langchain_tool.args_schema else {},
+        )
+
+    @staticmethod
+    def function_to_langchain(
+        func: Callable, name: Optional[str] = None, description: Optional[str] = None
+    ) -> BaseTool:
+        """
+        Convert a function to LangChain tool format.
+
+        Args:
+            func: Function to convert
+            name: Optional tool name (defaults to function name)
+            description: Optional tool description (defaults to function docstring)
+
+        Returns:
+            LangChain BaseTool instance
+        """
+        # Use function name if no name provided
+        tool_name = name if name is not None else func.__name__
+
+        # Use function docstring if no description provided
+        if description is not None:
+            tool_description = description
+        else:
+            # Use docstring and clean it up (add period if needed)
+            tool_description = func.__doc__ or ""
+            if tool_description and not tool_description.endswith("."):
+                tool_description = tool_description.strip() + "."
+
+        return tool(tool_name, description=tool_description)(func)
+
+
+class BaseToolkit(abc.ABC):
+    """
+    Base class for synchronous toolkits.
+
+    Provides a common interface for all toolkit implementations with support
+    for LangChain tools, configuration management, and logging.
+    """
+
+    def __init__(self, config: Optional[Union[ToolkitConfig, Dict[str, Any]]] = None):
+        """
+        Initialize the toolkit.
+
+        Args:
+            config: Toolkit configuration (ToolkitConfig instance or dict)
+        """
+        if isinstance(config, dict):
+            config = ToolkitConfig(**config)
+        elif config is None:
+            config = ToolkitConfig()
+
+        self.config = config
+        self.logger = get_logger(f"{self.__class__.__module__}.{self.__class__.__name__}")
+        self._tools_cache: Optional[Dict[str, Callable]] = None
+        self._llm_client: Optional[BaseLLMClient] = None
+
+    @property
+    def llm_client(self) -> BaseLLMClient:
+        """Get or create LLM client instance."""
+        if self._llm_client is None:
+            self._llm_client = self.config.get_llm_client()
+        return self._llm_client
+
+    @abc.abstractmethod
+    def get_tools_map(self) -> Dict[str, Callable]:
+        """
+        Get a mapping of tool names to their implementation functions.
+
+        Returns:
+            Dict mapping tool names to callable functions
+        """
+
+    def get_filtered_tools_map(self) -> Dict[str, Callable]:
+        """
+        Get tools map filtered by activated_tools configuration.
+
+        Returns:
+            Dict containing only activated tools
+        """
+        if self._tools_cache is None:
+            self._tools_cache = self.get_tools_map()
+
+        if self.config.activated_tools is None:
+            return self._tools_cache
+
+        # Validate that all activated tools exist
+        missing_tools = set(self.config.activated_tools) - set(self._tools_cache.keys())
+        if missing_tools:
+            raise ToolkitError(
+                f"Activated tools not found in {self.__class__.__name__}: {missing_tools}. "
+                f"Available tools: {list(self._tools_cache.keys())}"
+            )
+
+        return {name: self._tools_cache[name] for name in self.config.activated_tools}
+
+    def get_langchain_tools(self) -> List[BaseTool]:
+        """
+        Get tools in LangChain format.
+
+        Returns:
+            List of LangChain BaseTool instances
+        """
+        tools_map = self.get_filtered_tools_map()
+        return [ToolConverter.function_to_langchain(func, name) for name, func in tools_map.items()]
+
+    def get_mcp_tools(self) -> List["mcp_types.Tool"]:
+        """
+        Get tools in MCP format.
+
+        Returns:
+            List of MCP Tool instances
+
+        Raises:
+            MCPNotAvailableError: If MCP is not available
+        """
+        if not MCP_AVAILABLE:
+            raise MCPNotAvailableError("MCP package is not installed")
+
+        langchain_tools = self.get_langchain_tools()
+        return [ToolConverter.langchain_to_mcp(tool) for tool in langchain_tools]
+
+    def call_tool(self, name: str, **kwargs) -> Any:
+        """
+        Call a tool by name with the provided arguments.
+
+        Args:
+            name: Tool name
+            **kwargs: Tool arguments
+
+        Returns:
+            Tool execution result
+
+        Raises:
+            ToolkitError: If tool is not found
+        """
+        tools_map = self.get_filtered_tools_map()
+        if name not in tools_map:
+            raise ToolkitError(f"Tool '{name}' not found in {self.__class__.__name__}")
+
+        tool_func = tools_map[name]
+        self.logger.debug(f"Calling tool '{name}' with args: {kwargs}")
+
+        try:
+            result = tool_func(**kwargs)
+            self.logger.debug(f"Tool '{name}' completed successfully")
+            return result
+        except Exception as e:
+            self.logger.error(f"Tool '{name}' failed: {e}")
+            raise
+
+
+class AsyncBaseToolkit(BaseToolkit):
+    """
+    Base class for asynchronous toolkits.
+
+    Extends BaseToolkit with async support and lifecycle management.
+    """
+
+    def __init__(self, config: Optional[Union[ToolkitConfig, Dict[str, Any]]] = None):
+        """
+        Initialize the async toolkit.
+
+        Args:
+            config: Toolkit configuration (ToolkitConfig instance or dict)
+        """
+        super().__init__(config)
+        self._built = False
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self.build()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.cleanup()
+
+    async def build(self):
+        """
+        Build/initialize the toolkit.
+
+        Override this method to perform async initialization tasks.
+        """
+        if self._built:
+            return
+        self.logger.debug(f"Building {self.__class__.__name__}")
+        self._built = True
+
+    async def cleanup(self):
+        """
+        Cleanup toolkit resources.
+
+        Override this method to perform cleanup tasks.
+        """
+        self.logger.debug(f"Cleaning up {self.__class__.__name__}")
+        self._built = False
+
+    @abc.abstractmethod
+    async def get_tools_map(self) -> Dict[str, Callable]:
+        """
+        Get a mapping of tool names to their implementation functions.
+
+        Returns:
+            Dict mapping tool names to callable functions
+        """
+
+    async def get_filtered_tools_map(self) -> Dict[str, Callable]:
+        """
+        Get tools map filtered by activated_tools configuration.
+
+        Returns:
+            Dict containing only activated tools
+        """
+        if self._tools_cache is None:
+            self._tools_cache = await self.get_tools_map()
+
+        if self.config.activated_tools is None:
+            return self._tools_cache
+
+        # Validate that all activated tools exist
+        missing_tools = set(self.config.activated_tools) - set(self._tools_cache.keys())
+        if missing_tools:
+            raise ToolkitError(
+                f"Activated tools not found in {self.__class__.__name__}: {missing_tools}. "
+                f"Available tools: {list(self._tools_cache.keys())}"
+            )
+
+        return {name: self._tools_cache[name] for name in self.config.activated_tools}
+
+    async def get_langchain_tools(self) -> List[BaseTool]:
+        """
+        Get tools in LangChain format.
+
+        Returns:
+            List of LangChain BaseTool instances
+        """
+        tools_map = await self.get_filtered_tools_map()
+        return [ToolConverter.function_to_langchain(func, name) for name, func in tools_map.items()]
+
+    async def get_mcp_tools(self) -> List["mcp_types.Tool"]:
+        """
+        Get tools in MCP format.
+
+        Returns:
+            List of MCP Tool instances
+
+        Raises:
+            MCPNotAvailableError: If MCP is not available
+        """
+        if not MCP_AVAILABLE:
+            raise MCPNotAvailableError("MCP package is not installed")
+
+        langchain_tools = await self.get_langchain_tools()
+        return [ToolConverter.langchain_to_mcp(tool) for tool in langchain_tools]
+
+    async def call_tool(self, name: str, **kwargs) -> Any:
+        """
+        Call a tool by name with the provided arguments.
+
+        Args:
+            name: Tool name
+            **kwargs: Tool arguments
+
+        Returns:
+            Tool execution result
+
+        Raises:
+            ToolkitError: If tool is not found
+        """
+        tools_map = await self.get_filtered_tools_map()
+        if name not in tools_map:
+            raise ToolkitError(f"Tool '{name}' not found in {self.__class__.__name__}")
+
+        tool_func = tools_map[name]
+        self.logger.debug(f"Calling tool '{name}' with args: {kwargs}")
+
+        try:
+            # Handle both sync and async functions
+            if asyncio.iscoroutinefunction(tool_func):
+                result = await tool_func(**kwargs)
+            else:
+                result = tool_func(**kwargs)
+            self.logger.debug(f"Tool '{name}' completed successfully")
+            return result
+        except Exception as e:
+            self.logger.error(f"Tool '{name}' failed: {e}")
+            raise
+
+    # Sync compatibility methods
+    def get_tools_map_sync(self) -> Dict[str, Callable]:
+        """Synchronous version of get_tools_map for compatibility."""
+        loop = asyncio.get_event_loop()
+        if not self._built:
+            loop.run_until_complete(self.build())
+        return loop.run_until_complete(self.get_tools_map())
+
+    def get_langchain_tools_sync(self) -> List[BaseTool]:
+        """Synchronous version of get_langchain_tools for compatibility."""
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(self.get_langchain_tools())