rakam-systems-core 0.1.1rc7__py3-none-any.whl

rakam_systems_core/ai_core/interfaces/tool_loader.py

@@ -0,0 +1,374 @@
+"""
+Tool Loader for automatic tool discovery and registration from configuration.
+Supports loading tools from YAML/JSON config files and Python modules.
+"""
+from __future__ import annotations
+from typing import Any, Dict, List, Optional, Callable
+import importlib
+import inspect
+import yaml
+import json
+from pathlib import Path
+from .tool_registry import ToolRegistry
+from .tool import ToolComponent
+
+
+class ToolLoadError(Exception):
+    """Base exception for tool loading errors."""
+    pass
+
+
+class ToolLoader:
+    """
+    Load and register tools from configuration files.
+    
+    Supports:
+    - YAML and JSON configuration files
+    - Auto-discovery of tool functions from Python modules
+    - Dynamic import and registration
+    - Validation of tool definitions
+    
+    Configuration Format (YAML):
+        tools:
+          - name: calculate
+            type: direct
+            module: my_tools.math_tools
+            function: calculate
+            description: Add two numbers
+            category: math
+            tags: [arithmetic, basic]
+            schema:
+              type: object
+              properties:
+                x:
+                  type: integer
+                  description: First number
+                y:
+                  type: integer
+                  description: Second number
+              required: [x, y]
+          
+          - name: web_search
+            type: mcp
+            mcp_server: search_server
+            mcp_tool_name: search
+            description: Search the web
+            category: search
+            tags: [web, external]
+    
+    Example:
+        >>> loader = ToolLoader(registry)
+        >>> loader.load_from_yaml("tools.yaml")
+        >>> print(f"Loaded {len(registry)} tools")
+    """
+    
+    def __init__(self, registry: ToolRegistry):
+        """
+        Initialize the ToolLoader.
+        
+        Args:
+            registry: ToolRegistry instance to register tools into
+        """
+        self.registry = registry
+    
+    def load_from_yaml(self, file_path: str) -> int:
+        """
+        Load tools from a YAML configuration file.
+        
+        Args:
+            file_path: Path to YAML configuration file
+        
+        Returns:
+            Number of tools loaded
+        
+        Raises:
+            ToolLoadError: If file cannot be loaded or parsed
+        """
+        try:
+            with open(file_path, 'r') as f:
+                config = yaml.safe_load(f)
+            return self.load_from_config(config)
+        except FileNotFoundError:
+            raise ToolLoadError(f"Configuration file not found: {file_path}")
+        except yaml.YAMLError as e:
+            raise ToolLoadError(f"Failed to parse YAML file: {str(e)}") from e
+    
+    def load_from_json(self, file_path: str) -> int:
+        """
+        Load tools from a JSON configuration file.
+        
+        Args:
+            file_path: Path to JSON configuration file
+        
+        Returns:
+            Number of tools loaded
+        
+        Raises:
+            ToolLoadError: If file cannot be loaded or parsed
+        """
+        try:
+            with open(file_path, 'r') as f:
+                config = json.load(f)
+            return self.load_from_config(config)
+        except FileNotFoundError:
+            raise ToolLoadError(f"Configuration file not found: {file_path}")
+        except json.JSONDecodeError as e:
+            raise ToolLoadError(f"Failed to parse JSON file: {str(e)}") from e
+    
+    def load_from_config(self, config: Dict[str, Any]) -> int:
+        """
+        Load tools from a configuration dictionary.
+        
+        Args:
+            config: Configuration dictionary
+        
+        Returns:
+            Number of tools loaded
+        
+        Raises:
+            ToolLoadError: If configuration is invalid
+        """
+        if not isinstance(config, dict):
+            raise ToolLoadError("Configuration must be a dictionary")
+        
+        tools_config = config.get('tools', [])
+        if not isinstance(tools_config, list):
+            raise ToolLoadError("'tools' must be a list")
+        
+        loaded_count = 0
+        errors = []
+        
+        for tool_config in tools_config:
+            try:
+                self._load_tool(tool_config)
+                loaded_count += 1
+            except Exception as e:
+                tool_name = tool_config.get('name', 'unknown')
+                errors.append(f"Failed to load tool '{tool_name}': {str(e)}")
+        
+        if errors:
+            error_msg = "\n".join(errors)
+            raise ToolLoadError(f"Errors loading tools:\n{error_msg}")
+        
+        return loaded_count
+    
+    def _load_tool(self, tool_config: Dict[str, Any]) -> None:
+        """Load a single tool from configuration."""
+        # Validate required fields
+        if 'name' not in tool_config:
+            raise ToolLoadError("Tool configuration must have 'name' field")
+        
+        name = tool_config['name']
+        tool_type = tool_config.get('type', 'direct')
+        description = tool_config.get('description', f"Tool: {name}")
+        category = tool_config.get('category')
+        tags = tool_config.get('tags', [])
+        
+        if tool_type == 'direct':
+            self._load_direct_tool(name, tool_config, description, category, tags)
+        elif tool_type == 'mcp':
+            self._load_mcp_tool(name, tool_config, description, category, tags)
+        else:
+            raise ToolLoadError(f"Unknown tool type: {tool_type}")
+    
+    def _load_direct_tool(
+        self,
+        name: str,
+        config: Dict[str, Any],
+        description: str,
+        category: Optional[str],
+        tags: List[str]
+    ) -> None:
+        """Load a direct tool from configuration."""
+        # Get module and function name
+        module_name = config.get('module')
+        function_name = config.get('function')
+        
+        if not module_name or not function_name:
+            raise ToolLoadError(
+                f"Direct tool '{name}' must specify 'module' and 'function'"
+            )
+        
+        # Import the function
+        try:
+            module = importlib.import_module(module_name)
+            function = getattr(module, function_name)
+        except ImportError as e:
+            raise ToolLoadError(
+                f"Failed to import module '{module_name}': {str(e)}"
+            ) from e
+        except AttributeError as e:
+            raise ToolLoadError(
+                f"Function '{function_name}' not found in module '{module_name}'"
+            ) from e
+        
+        if not callable(function):
+            raise ToolLoadError(
+                f"'{module_name}.{function_name}' is not callable"
+            )
+        
+        # Get or generate JSON schema
+        json_schema = config.get('schema')
+        if json_schema is None:
+            # Try to auto-generate schema from function signature
+            json_schema = self._generate_schema_from_function(function)
+        
+        # Check if function takes context
+        takes_ctx = config.get('takes_ctx', False)
+        
+        # Register the tool
+        self.registry.register_direct_tool(
+            name=name,
+            function=function,
+            description=description,
+            json_schema=json_schema,
+            takes_ctx=takes_ctx,
+            category=category,
+            tags=tags,
+        )
+    
+    def _load_mcp_tool(
+        self,
+        name: str,
+        config: Dict[str, Any],
+        description: str,
+        category: Optional[str],
+        tags: List[str]
+    ) -> None:
+        """Load an MCP tool from configuration."""
+        mcp_server = config.get('mcp_server')
+        mcp_tool_name = config.get('mcp_tool_name', name)
+        
+        if not mcp_server:
+            raise ToolLoadError(f"MCP tool '{name}' must specify 'mcp_server'")
+        
+        # Register the MCP tool
+        self.registry.register_mcp_tool(
+            name=name,
+            mcp_server=mcp_server,
+            mcp_tool_name=mcp_tool_name,
+            description=description,
+            category=category,
+            tags=tags,
+        )
+    
+    def _generate_schema_from_function(self, function: Callable) -> Dict[str, Any]:
+        """
+        Auto-generate a JSON schema from function signature.
+        
+        Note: This is a basic implementation. For production use,
+        consider using pydantic or similar for better type inference.
+        """
+        sig = inspect.signature(function)
+        properties = {}
+        required = []
+        
+        for param_name, param in sig.parameters.items():
+            # Skip self, cls, and context parameters
+            if param_name in ('self', 'cls', 'ctx', 'context'):
+                continue
+            
+            param_schema = {'type': 'string'}  # Default type
+            
+            # Try to infer type from annotation
+            if param.annotation != inspect.Parameter.empty:
+                param_schema['type'] = self._python_type_to_json_type(param.annotation)
+            
+            properties[param_name] = param_schema
+            
+            # Check if parameter is required
+            if param.default == inspect.Parameter.empty:
+                required.append(param_name)
+        
+        schema = {
+            'type': 'object',
+            'properties': properties,
+            'additionalProperties': False,
+        }
+        
+        if required:
+            schema['required'] = required
+        
+        return schema
+    
+    def _python_type_to_json_type(self, python_type: Any) -> str:
+        """Convert Python type annotation to JSON schema type."""
+        type_mapping = {
+            int: 'integer',
+            float: 'number',
+            str: 'string',
+            bool: 'boolean',
+            list: 'array',
+            dict: 'object',
+        }
+        
+        # Handle Optional types
+        if hasattr(python_type, '__origin__'):
+            origin = python_type.__origin__
+            if origin is list:
+                return 'array'
+            elif origin is dict:
+                return 'object'
+        
+        # Direct type mapping
+        return type_mapping.get(python_type, 'string')
+    
+    def load_from_directory(
+        self,
+        directory: str,
+        pattern: str = "*.yaml",
+        recursive: bool = False
+    ) -> int:
+        """
+        Load tools from all configuration files in a directory.
+        
+        Args:
+            directory: Path to directory containing configuration files
+            pattern: Glob pattern for configuration files (default: "*.yaml")
+            recursive: Whether to search recursively (default: False)
+        
+        Returns:
+            Total number of tools loaded
+        
+        Raises:
+            ToolLoadError: If directory not found or files cannot be loaded
+        """
+        path = Path(directory)
+        if not path.exists():
+            raise ToolLoadError(f"Directory not found: {directory}")
+        
+        if not path.is_dir():
+            raise ToolLoadError(f"Not a directory: {directory}")
+        
+        # Find all matching files
+        if recursive:
+            files = list(path.rglob(pattern))
+        else:
+            files = list(path.glob(pattern))
+        
+        if not files:
+            raise ToolLoadError(
+                f"No configuration files found matching '{pattern}' in {directory}"
+            )
+        
+        total_loaded = 0
+        errors = []
+        
+        for file_path in files:
+            try:
+                if file_path.suffix in ['.yaml', '.yml']:
+                    count = self.load_from_yaml(str(file_path))
+                elif file_path.suffix == '.json':
+                    count = self.load_from_json(str(file_path))
+                else:
+                    continue
+                total_loaded += count
+            except Exception as e:
+                errors.append(f"Error loading {file_path}: {str(e)}")
+        
+        if errors:
+            error_msg = "\n".join(errors)
+            raise ToolLoadError(f"Errors loading tools:\n{error_msg}")
+        
+        return total_loaded
+

rakam_systems_core/ai_core/interfaces/tool_registry.py

@@ -0,0 +1,287 @@
+"""
+Tool Registry for managing and discovering tools across the system.
+Provides a centralized registry for both direct tool invocation and MCP-based tools.
+"""
+from __future__ import annotations
+from typing import Dict, List, Optional, Any, Callable, Union
+from abc import ABC, abstractmethod
+import inspect
+from .tool import ToolComponent
+
+
+class ToolMode:
+    """Constants for tool invocation modes."""
+    DIRECT = "direct"
+    MCP = "mcp"
+
+
+class ToolMetadata:
+    """Metadata for a registered tool."""
+    
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        mode: str,
+        tool_instance: Optional[ToolComponent] = None,
+        mcp_server: Optional[str] = None,
+        mcp_tool_name: Optional[str] = None,
+        category: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ):
+        self.name = name
+        self.description = description
+        self.mode = mode
+        self.tool_instance = tool_instance
+        self.mcp_server = mcp_server
+        self.mcp_tool_name = mcp_tool_name
+        self.category = category or "general"
+        self.tags = tags or []
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert metadata to dictionary format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "mode": self.mode,
+            "mcp_server": self.mcp_server,
+            "mcp_tool_name": self.mcp_tool_name,
+            "category": self.category,
+            "tags": self.tags,
+        }
+
+
+class ToolRegistry:
+    """
+    Central registry for managing tools in the system.
+    
+    Supports:
+    - Direct tool registration (callable functions or Tool instances)
+    - MCP-based tool registration (tools exposed via MCP servers)
+    - Tool discovery and lookup by name, category, or tags
+    - Automatic tool conversion for different agent frameworks
+    
+    Example:
+        >>> registry = ToolRegistry()
+        >>> 
+        >>> # Register a direct tool
+        >>> def calculate(x: int, y: int) -> int:
+        ...     return x + y
+        >>> registry.register_direct_tool(
+        ...     name="calculate",
+        ...     function=calculate,
+        ...     description="Add two numbers",
+        ...     json_schema={...}
+        ... )
+        >>>
+        >>> # Register an MCP tool
+        >>> registry.register_mcp_tool(
+        ...     name="search",
+        ...     mcp_server="search_server",
+        ...     mcp_tool_name="web_search",
+        ...     description="Search the web"
+        ... )
+        >>>
+        >>> # Get all tools
+        >>> tools = registry.get_all_tools()
+    """
+    
+    def __init__(self):
+        self._tools: Dict[str, ToolMetadata] = {}
+        self._categories: Dict[str, List[str]] = {}
+        self._tags: Dict[str, List[str]] = {}
+    
+    def register_direct_tool(
+        self,
+        name: str,
+        function: Callable[..., Any],
+        description: str,
+        json_schema: Dict[str, Any],
+        takes_ctx: bool = False,
+        category: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Register a tool for direct invocation.
+        
+        Args:
+            name: Unique name for the tool
+            function: The callable function
+            description: Human-readable description
+            json_schema: JSON schema for the tool parameters
+            takes_ctx: Whether the tool takes context as first argument
+            category: Optional category for organizing tools
+            tags: Optional tags for filtering tools
+        """
+        # Create a ToolComponent from the function
+        tool = ToolComponent.from_function(
+            function=function,
+            name=name,
+            description=description,
+            json_schema=json_schema,
+            takes_ctx=takes_ctx,
+        )
+        
+        metadata = ToolMetadata(
+            name=name,
+            description=description,
+            mode=ToolMode.DIRECT,
+            tool_instance=tool,
+            category=category,
+            tags=tags,
+        )
+        
+        self._register_metadata(metadata)
+    
+    def register_tool_instance(
+        self,
+        tool: ToolComponent,
+        category: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Register an existing ToolComponent instance.
+        
+        Args:
+            tool: ToolComponent instance
+            category: Optional category for organizing tools
+            tags: Optional tags for filtering tools
+        """
+        if not isinstance(tool, ToolComponent):
+            raise ValueError(f"Unsupported tool type: {type(tool)}. Expected ToolComponent.")
+        
+        metadata = ToolMetadata(
+            name=tool.name,
+            description=tool.description,
+            mode=ToolMode.DIRECT,
+            tool_instance=tool,
+            category=category,
+            tags=tags,
+        )
+        
+        self._register_metadata(metadata)
+    
+    def register_mcp_tool(
+        self,
+        name: str,
+        mcp_server: str,
+        mcp_tool_name: str,
+        description: str,
+        category: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Register a tool that will be invoked via MCP server.
+        
+        Args:
+            name: Unique name for the tool in this registry
+            mcp_server: Name of the MCP server hosting the tool
+            mcp_tool_name: Name of the tool on the MCP server
+            description: Human-readable description
+            category: Optional category for organizing tools
+            tags: Optional tags for filtering tools
+        """
+        metadata = ToolMetadata(
+            name=name,
+            description=description,
+            mode=ToolMode.MCP,
+            mcp_server=mcp_server,
+            mcp_tool_name=mcp_tool_name,
+            category=category,
+            tags=tags,
+        )
+        
+        self._register_metadata(metadata)
+    
+    def _register_metadata(self, metadata: ToolMetadata) -> None:
+        """Internal method to register tool metadata and update indices."""
+        if metadata.name in self._tools:
+            raise ValueError(f"Tool '{metadata.name}' is already registered")
+        
+        self._tools[metadata.name] = metadata
+        
+        # Update category index
+        if metadata.category not in self._categories:
+            self._categories[metadata.category] = []
+        self._categories[metadata.category].append(metadata.name)
+        
+        # Update tag index
+        for tag in metadata.tags:
+            if tag not in self._tags:
+                self._tags[tag] = []
+            self._tags[tag].append(metadata.name)
+    
+    def get_tool(self, name: str) -> Optional[ToolMetadata]:
+        """Get tool metadata by name."""
+        return self._tools.get(name)
+    
+    def get_all_tools(self) -> List[ToolMetadata]:
+        """Get all registered tools."""
+        return list(self._tools.values())
+    
+    def get_tools_by_category(self, category: str) -> List[ToolMetadata]:
+        """Get all tools in a specific category."""
+        tool_names = self._categories.get(category, [])
+        return [self._tools[name] for name in tool_names]
+    
+    def get_tools_by_tag(self, tag: str) -> List[ToolMetadata]:
+        """Get all tools with a specific tag."""
+        tool_names = self._tags.get(tag, [])
+        return [self._tools[name] for name in tool_names]
+    
+    def get_tools_by_mode(self, mode: str) -> List[ToolMetadata]:
+        """Get all tools for a specific invocation mode."""
+        return [tool for tool in self._tools.values() if tool.mode == mode]
+    
+    def list_categories(self) -> List[str]:
+        """List all registered categories."""
+        return list(self._categories.keys())
+    
+    def list_tags(self) -> List[str]:
+        """List all registered tags."""
+        return list(self._tags.keys())
+    
+    def unregister_tool(self, name: str) -> bool:
+        """
+        Unregister a tool by name.
+        
+        Returns:
+            True if tool was unregistered, False if not found
+        """
+        if name not in self._tools:
+            return False
+        
+        metadata = self._tools[name]
+        
+        # Remove from indices
+        if metadata.category in self._categories:
+            self._categories[metadata.category].remove(name)
+            if not self._categories[metadata.category]:
+                del self._categories[metadata.category]
+        
+        for tag in metadata.tags:
+            if tag in self._tags:
+                self._tags[tag].remove(name)
+                if not self._tags[tag]:
+                    del self._tags[tag]
+        
+        del self._tools[name]
+        return True
+    
+    def clear(self) -> None:
+        """Clear all registered tools."""
+        self._tools.clear()
+        self._categories.clear()
+        self._tags.clear()
+    
+    def __len__(self) -> int:
+        """Return number of registered tools."""
+        return len(self._tools)
+    
+    def __contains__(self, name: str) -> bool:
+        """Check if a tool is registered."""
+        return name in self._tools
+    
+    def __repr__(self) -> str:
+        return f"ToolRegistry(tools={len(self._tools)}, categories={len(self._categories)}, tags={len(self._tags)})"
+

rakam_systems_core/ai_core/interfaces/vectorstore.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from ..base import BaseComponent
+
+
+class VectorStore(BaseComponent, ABC):
+    @abstractmethod
+    def add(self, vectors: List[List[float]], metadatas: List[Dict[str, Any]]) -> Any:
+        raise NotImplementedError
+
+    @abstractmethod
+    def query(self, vector: List[float], top_k: int = 5) -> List[Dict[str, Any]]:
+        raise NotImplementedError
+
+    def run(self, *args, **kwargs):
+        """
+        Convenience default so subclasses don't *have* to implement run().
+        If called with a 'vector' (or first positional arg), proxies to query().
+        """
+        vector = kwargs.get("vector")
+        if vector is None and args:
+            vector = args[0]
+        top_k = kwargs.get("top_k", 5)
+        if vector is None:
+            raise NotImplementedError(
+                "VectorStore.run expects a 'vector' argument or an override."
+            )
+        return self.query(vector, top_k=top_k)
+
+    def count(self) -> Optional[int]:
+        return None
+
+
+# compatibility alias
+VectorStoreComponent = VectorStore
+__all__ = ["VectorStore", "VectorStoreComponent"]