alita-sdk 0.3.462__py3-none-any.whl → 0.3.627__py3-none-any.whl

alita_sdk/runtime/skills/registry.py

@@ -0,0 +1,355 @@
+"""
+Skills Registry service for managing and querying skills.
+
+This module provides a thread-safe registry service that uses the discovery
+service to find skills and provides a clean API for skill management.
+"""
+
+import logging
+import threading
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .discovery import SkillDiscovery
+from .models import SkillMetadata, SkillType
+
+logger = logging.getLogger(__name__)
+
+
+class SkillsRegistry:
+    """
+    Thread-safe registry service for managing skills.
+
+    The registry uses a discovery service to find skills and provides
+    a clean API for querying, filtering, and managing skills.
+    """
+
+    def __init__(self, search_paths: Optional[List[str]] = None):
+        """
+        Initialize the skills registry.
+
+        Args:
+            search_paths: Custom search paths for skills. If None, uses defaults.
+        """
+        self.discovery = SkillDiscovery(search_paths)
+        self._lock = threading.RLock()
+        self._initialized = False
+
+        logger.info("Skills registry initialized")
+
+    def discover(self, refresh: bool = False) -> Dict[str, SkillMetadata]:
+        """
+        Discover skills from configured search paths.
+
+        This is the primary method to populate the registry with skills.
+        It's thread-safe and can be called multiple times.
+
+        Args:
+            refresh: If True, clear cache and rescan all directories.
+
+        Returns:
+            Dictionary mapping skill names to SkillMetadata objects.
+        """
+        with self._lock:
+            skills = self.discovery.discover(refresh=refresh)
+            self._initialized = True
+            logger.info(f"Registry discovered {len(skills)} skills")
+            return skills
+
+    def list(self) -> List[SkillMetadata]:
+        """
+        Get list of all discovered skills.
+
+        Returns:
+            List of SkillMetadata objects.
+        """
+        with self._lock:
+            if not self._initialized:
+                self.discover()
+            return list(self.discovery.cache.values())
+
+    def get(self, name: str) -> Optional[SkillMetadata]:
+        """
+        Get a skill by name.
+
+        Args:
+            name: Name of the skill to retrieve.
+
+        Returns:
+            SkillMetadata if found, None otherwise.
+        """
+        with self._lock:
+            if not self._initialized:
+                self.discover()
+            return self.discovery.get_skill_by_name(name)
+
+    def find_by_capability(self, capability: str) -> List[SkillMetadata]:
+        """
+        Find skills that provide a specific capability.
+
+        Args:
+            capability: Capability to search for.
+
+        Returns:
+            List of matching SkillMetadata objects.
+        """
+        with self._lock:
+            if not self._initialized:
+                self.discover()
+            return self.discovery.find_skills_by_capability(capability)
+
+    def find_by_tag(self, tag: str) -> List[SkillMetadata]:
+        """
+        Find skills with a specific tag.
+
+        Args:
+            tag: Tag to search for.
+
+        Returns:
+            List of matching SkillMetadata objects.
+        """
+        with self._lock:
+            if not self._initialized:
+                self.discover()
+            return self.discovery.find_skills_by_tag(tag)
+
+    def find_by_type(self, skill_type: SkillType) -> List[SkillMetadata]:
+        """
+        Find skills of a specific type (graph or agent).
+
+        Args:
+            skill_type: SkillType to filter by.
+
+        Returns:
+            List of matching SkillMetadata objects.
+        """
+        with self._lock:
+            if not self._initialized:
+                self.discover()
+            return self.discovery.find_skills_by_type(skill_type)
+
+    def reload(self, name: str) -> Optional[SkillMetadata]:
+        """
+        Reload a specific skill from disk.
+
+        This is useful when you know a specific skill has been updated
+        and you want to reload just that skill without refreshing all.
+
+        Args:
+            name: Name of the skill to reload.
+
+        Returns:
+            Updated SkillMetadata if found and reloaded, None otherwise.
+        """
+        with self._lock:
+            # Get current skill to know where to look
+            current_skill = self.get(name)
+            if not current_skill:
+                logger.warning(f"Cannot reload skill '{name}': not found in registry")
+                return None
+
+            skill_path = Path(current_skill.path)
+            agent_file = skill_path / "agent.md"
+
+            try:
+                # Parse the skill file directly
+                updated_skill = self.discovery._parse_skill_file(agent_file)
+                if updated_skill and updated_skill.name == name:
+                    # Update cache with reloaded skill
+                    self.discovery.cache[name] = updated_skill
+                    logger.info(f"Successfully reloaded skill: {name}")
+                    return updated_skill
+                else:
+                    logger.error(f"Reloaded skill name mismatch: expected '{name}', got '{updated_skill.name if updated_skill else None}'")
+                    return None
+
+            except Exception as e:
+                logger.error(f"Failed to reload skill '{name}': {e}")
+                return None
+
+    def clear(self) -> None:
+        """
+        Clear the registry cache.
+
+        This removes all cached skills. The next query will trigger
+        a fresh discovery.
+        """
+        with self._lock:
+            self.discovery.cache.clear()
+            self._initialized = False
+            logger.info("Registry cache cleared")
+
+    def is_skill_valid(self, name: str) -> bool:
+        """
+        Check if a skill exists and is valid.
+
+        Args:
+            name: Name of the skill to check.
+
+        Returns:
+            True if skill exists and is valid, False otherwise.
+        """
+        skill = self.get(name)
+        return skill is not None
+
+    def validate_skill_at_path(self, skill_path: str) -> tuple[bool, Optional[str]]:
+        """
+        Validate a skill definition at a specific path.
+
+        This can be used to validate a skill before adding it to
+        the registry or to check if a skill definition is valid.
+
+        Args:
+            skill_path: Path to skill directory containing agent.md.
+
+        Returns:
+            Tuple of (is_valid, error_message).
+        """
+        return self.discovery.validate_skill_definition(Path(skill_path))
+
+    def get_registry_stats(self) -> Dict[str, int]:
+        """
+        Get statistics about the registry contents.
+
+        Returns:
+            Dictionary with registry statistics.
+        """
+        with self._lock:
+            if not self._initialized:
+                self.discover()
+
+            stats = {
+                "total_skills": len(self.discovery.cache),
+                "graph_skills": len(self.find_by_type(SkillType.GRAPH)),
+                "agent_skills": len(self.find_by_type(SkillType.AGENT))
+            }
+
+            # Count unique capabilities and tags
+            all_capabilities = set()
+            all_tags = set()
+            for skill in self.discovery.cache.values():
+                all_capabilities.update(skill.capabilities)
+                all_tags.update(skill.tags)
+
+            stats["unique_capabilities"] = len(all_capabilities)
+            stats["unique_tags"] = len(all_tags)
+
+            return stats
+
+    def get_skills_by_search_path(self) -> Dict[str, List[SkillMetadata]]:
+        """
+        Get skills grouped by their search path.
+
+        This is useful for understanding which skills come from which
+        directories and for debugging discovery issues.
+
+        Returns:
+            Dictionary mapping search paths to lists of skills.
+        """
+        with self._lock:
+            if not self._initialized:
+                self.discover()
+
+            path_groups = {}
+            for skill in self.discovery.cache.values():
+                skill_path = Path(skill.path)
+
+                # Find which search path this skill belongs to
+                for search_path in self.discovery.search_paths:
+                    search_path_obj = Path(search_path).expanduser().resolve()
+                    try:
+                        if skill_path.is_relative_to(search_path_obj):
+                            if search_path not in path_groups:
+                                path_groups[search_path] = []
+                            path_groups[search_path].append(skill)
+                            break
+                    except (ValueError, OSError):
+                        # skill_path is not relative to this search path
+                        continue
+
+            return path_groups
+
+    def refresh_if_stale(self, max_age_seconds: int = 300) -> bool:
+        """
+        Refresh the registry if it's considered stale.
+
+        Args:
+            max_age_seconds: Maximum age in seconds before refresh.
+
+        Returns:
+            True if refresh was performed, False if cache is still fresh.
+        """
+        # This is a simple implementation - in production you might want
+        # to track file modification times or use a more sophisticated
+        # staleness check
+        with self._lock:
+            if not self._initialized:
+                self.discover()
+                return True
+
+            # For now, always consider the cache fresh since we don't
+            # track timestamps. This method provides the interface
+            # for future enhancement.
+            # TODO: Implement actual staleness check using max_age_seconds
+            _ = max_age_seconds  # Suppress unused parameter warning
+            return False
+
+    def __len__(self) -> int:
+        """Return the number of skills in the registry."""
+        return len(self.list())
+
+    def __contains__(self, name: str) -> bool:
+        """Check if a skill name exists in the registry."""
+        return self.is_skill_valid(name)
+
+    def __repr__(self) -> str:
+        """String representation of the registry."""
+        stats = self.get_registry_stats()
+        return (
+            f"SkillsRegistry("
+            f"skills={stats['total_skills']}, "
+            f"graphs={stats['graph_skills']}, "
+            f"agents={stats['agent_skills']})"
+        )
+
+
+# Global registry instance for convenience
+_default_registry: Optional[SkillsRegistry] = None
+_registry_lock = threading.Lock()
+
+
+def get_default_registry() -> SkillsRegistry:
+    """
+    Get the default global skills registry instance.
+
+    This provides a convenient way to access a shared registry
+    without having to pass it around. The registry is created
+    lazily on first access.
+
+    Returns:
+        Default SkillsRegistry instance.
+    """
+    global _default_registry
+
+    with _registry_lock:
+        if _default_registry is None:
+            _default_registry = SkillsRegistry()
+            logger.info("Created default skills registry")
+
+        return _default_registry
+
+
+def reset_default_registry() -> None:
+    """
+    Reset the default registry instance.
+
+    This is mainly useful for testing or when you want to
+    reinitialize the registry with different settings.
+    """
+    global _default_registry
+
+    with _registry_lock:
+        if _default_registry is not None:
+            _default_registry.clear()
+        _default_registry = None
+        logger.info("Reset default skills registry")

alita_sdk/runtime/skills/skill_runner.py

@@ -0,0 +1,330 @@
+"""
+Skill runner subprocess entry point.
+
+This module is executed as a subprocess by the skill executor to run
+individual skills in isolation. It handles both graph and agent skills
+using the existing alita-sdk infrastructure.
+"""
+
+import argparse
+import json
+import logging
+import os
+import sys
+import traceback
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# Configure logging for subprocess
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    stream=sys.stderr
+)
+
+logger = logging.getLogger(__name__)
+
+# Import alita-sdk components
+try:
+    from ..langchain.assistant import Assistant
+    from ..langchain.langraph_agent import create_graph
+    from ..clients.client import AlitaClient
+    from .models import SkillMetadata, SkillType, SkillStatus
+except ImportError as e:
+    logger.error(f"Failed to import alita-sdk components: {e}")
+    sys.exit(1)
+
+
+class SkillRunner:
+    """
+    Subprocess skill runner that executes individual skills.
+    """
+
+    def __init__(self):
+        self.work_dir = None
+        self.skill_metadata = None
+        self.skill_input = None
+        self.execution_id = None
+
+    def run(self, input_file: Path, work_dir: Path) -> None:
+        """
+        Run a skill based on input file configuration.
+
+        Args:
+            input_file: Path to JSON input file with skill configuration.
+            work_dir: Working directory for execution.
+        """
+        self.work_dir = work_dir
+        result_file = work_dir / "skill_result.json"
+
+        try:
+            # Load input configuration
+            self._load_input(input_file)
+
+            # Execute skill based on type
+            if self.skill_metadata.skill_type == SkillType.AGENT:
+                result = self._run_agent_skill()
+            else:  # SkillType.GRAPH
+                result = self._run_graph_skill()
+
+            # Write successful result
+            self._write_result(result_file, {
+                'status': 'success',
+                'output_text': result,
+                'execution_id': self.execution_id
+            })
+
+            logger.info(f"Skill '{self.skill_metadata.name}' completed successfully")
+
+        except Exception as e:
+            logger.error(f"Skill execution failed: {e}")
+            logger.error(traceback.format_exc())
+
+            # Write error result
+            self._write_result(result_file, {
+                'status': 'error',
+                'output_text': f"Skill execution failed: {str(e)}",
+                'error_details': str(e),
+                'execution_id': self.execution_id
+            })
+
+            # Exit with error code
+            sys.exit(1)
+
+    def _load_input(self, input_file: Path) -> None:
+        """
+        Load skill configuration and input from JSON file.
+
+        Args:
+            input_file: Path to input JSON file.
+        """
+        try:
+            with open(input_file, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+
+            # Recreate SkillMetadata from dict
+            self.skill_metadata = SkillMetadata(**data['skill_metadata'])
+            self.skill_input = data['skill_input']
+            self.execution_id = data['execution_id']
+
+            logger.info(f"Loaded skill '{self.skill_metadata.name}' ({self.skill_metadata.skill_type.value})")
+
+        except Exception as e:
+            raise RuntimeError(f"Failed to load input file {input_file}: {e}")
+
+    def _run_agent_skill(self) -> str:
+        """
+        Run an agent-type skill using the Assistant framework.
+
+        Returns:
+            Skill execution result as text.
+        """
+        logger.info("Executing agent skill")
+
+        # Create mock AlitaClient (in production this would be passed or configured)
+        # For subprocess execution, we need to handle this differently
+        alita_client = self._create_mock_client()
+
+        # Create LLM client
+        llm = self._create_llm_client()
+
+        # Build agent data structure compatible with Assistant
+        agent_data = self._build_agent_data_structure()
+
+        # Create Assistant instance
+        assistant = Assistant(
+            alita=alita_client,
+            data=agent_data,
+            client=llm,
+            chat_history=self.skill_input.get('chat_history', []),
+            app_type=self.skill_metadata.agent_type or 'react',
+            tools=[]  # TODO: Load tools based on toolkit configuration
+        )
+
+        # Execute agent
+        agent_executor = assistant.runnable()
+        result = agent_executor.invoke({
+            'input': self.skill_input['input'],
+            'chat_history': self.skill_input.get('chat_history', []),
+            **self.skill_input.get('variables', {})
+        })
+
+        # Extract output text
+        if isinstance(result, dict):
+            output_text = result.get('output', str(result))
+        else:
+            output_text = str(result)
+
+        return output_text
+
+    def _run_graph_skill(self) -> str:
+        """
+        Run a graph-type skill using the LangGraph framework.
+
+        Returns:
+            Skill execution result as text.
+        """
+        logger.info("Executing graph skill")
+
+        # Create LLM client
+        llm = self._create_llm_client()
+
+        # Create graph from skill's YAML definition
+        if not self.skill_metadata.graph_yaml:
+            raise ValueError("Graph skill missing YAML definition")
+
+        graph = create_graph(
+            client=llm,
+            yaml_schema=self.skill_metadata.graph_yaml,
+            tools=[],  # TODO: Load tools based on configuration
+            memory=None,  # TODO: Configure memory if needed
+            store=None   # TODO: Configure store if needed
+        )
+
+        # Execute graph with state input
+        result = graph.invoke(self.skill_input)
+
+        # Extract output from graph result
+        if isinstance(result, dict):
+            # Try to get 'output' field first, then look for other relevant fields
+            output_text = (result.get('output') or
+                          result.get('messages', [{}])[-1].get('content', '') or
+                          str(result))
+        else:
+            output_text = str(result)
+
+        return output_text
+
+    def _build_agent_data_structure(self) -> Dict[str, Any]:
+        """
+        Build agent data structure compatible with Assistant.
+
+        Returns:
+            Agent configuration dictionary.
+        """
+        # Build LLM settings
+        llm_settings = {
+            'model_name': self.skill_metadata.model or 'gpt-4o',
+            'temperature': self.skill_metadata.temperature or 0.7,
+            'max_tokens': self.skill_metadata.max_tokens or 2000,
+            'top_p': 1.0,
+            'top_k': -1
+        }
+
+        # Build tools configuration from toolkits
+        tools = []
+        if self.skill_metadata.toolkits:
+            for toolkit_config in self.skill_metadata.toolkits:
+                # Convert toolkit config to tool format expected by Assistant
+                tools.append({
+                    'type': toolkit_config.get('type', 'unknown'),
+                    'name': toolkit_config.get('name', toolkit_config.get('type')),
+                    'toolkit_name': toolkit_config.get('type'),
+                    'config_ref': toolkit_config.get('config_ref')
+                })
+
+        return {
+            'name': self.skill_metadata.name,
+            'description': self.skill_metadata.description,
+            'llm_settings': llm_settings,
+            'agent_type': self.skill_metadata.agent_type or 'react',
+            'system_prompt': self.skill_metadata.system_prompt,
+            'tools': tools,
+            'meta': {
+                'step_limit': 25  # Default step limit
+            }
+        }
+
+    def _create_mock_client(self):
+        """
+        Create a mock AlitaClient for subprocess execution.
+
+        In a real implementation, this would be properly configured
+        or passed from the parent process.
+        """
+        # TODO: Implement proper client creation based on configuration
+        # For now, return None - the Assistant should handle this gracefully
+        return None
+
+    def _create_llm_client(self):
+        """
+        Create LLM client based on skill metadata.
+
+        Returns:
+            Configured LLM client.
+        """
+        # TODO: Implement proper LLM client creation
+        # This would typically involve:
+        # 1. Reading API keys from environment
+        # 2. Creating appropriate LLM instance based on model
+        # 3. Configuring with skill-specific settings
+
+        # For now, return a placeholder that indicates LLM is needed
+        class MockLLM:
+            def __init__(self):
+                self.model_name = self.skill_metadata.model or 'gpt-4o'
+                self.temperature = self.skill_metadata.temperature or 0.7
+                self.max_tokens = self.skill_metadata.max_tokens or 2000
+
+            def invoke(self, messages, **kwargs):
+                # This is a placeholder - in real implementation this would
+                # call the actual LLM API
+                return f"Mock LLM response for: {messages[-1] if messages else 'empty input'}"
+
+        return MockLLM()
+
+    def _write_result(self, result_file: Path, result_data: Dict[str, Any]) -> None:
+        """
+        Write execution result to file for parent process.
+
+        Args:
+            result_file: Path to result file.
+            result_data: Result data to write.
+        """
+        try:
+            with open(result_file, 'w', encoding='utf-8') as f:
+                json.dump(result_data, f, indent=2, default=str)
+        except Exception as e:
+            logger.error(f"Failed to write result file: {e}")
+            raise
+
+
+def main():
+    """
+    Main entry point for skill runner subprocess.
+    """
+    parser = argparse.ArgumentParser(description="Alita Skills Runner")
+    parser.add_argument(
+        '--input-file',
+        type=Path,
+        required=True,
+        help="Path to JSON input file with skill configuration"
+    )
+    parser.add_argument(
+        '--work-dir',
+        type=Path,
+        required=True,
+        help="Working directory for skill execution"
+    )
+
+    args = parser.parse_args()
+
+    # Validate arguments
+    if not args.input_file.exists():
+        logger.error(f"Input file does not exist: {args.input_file}")
+        sys.exit(1)
+
+    if not args.work_dir.exists():
+        logger.error(f"Working directory does not exist: {args.work_dir}")
+        sys.exit(1)
+
+    # Change to working directory
+    os.chdir(args.work_dir)
+
+    # Run skill
+    runner = SkillRunner()
+    runner.run(args.input_file, args.work_dir)
+
+
+if __name__ == '__main__':
+    main()

alita_sdk/runtime/toolkits/__init__.py

@@ -6,19 +6,26 @@ This module provides various toolkit implementations for LangGraph agents.
 from .application import ApplicationToolkit
 from .artifact import ArtifactToolkit
 from .datasource import DatasourcesToolkit
+from .planning import PlanningToolkit
 from .prompt import PromptToolkit
 from .subgraph import SubgraphToolkit
 from .vectorstore import VectorStoreToolkit
 from .mcp import McpToolkit
+from .mcp_config import McpConfigToolkit, get_session_manager as get_mcp_session_manager
+from .skill_router import SkillRouterToolkit
 from ...tools.memory import MemoryToolkit
 
 __all__ = [
     "ApplicationToolkit",
     "ArtifactToolkit",
     "DatasourcesToolkit",
+    "PlanningToolkit",
     "PromptToolkit",
     "SubgraphToolkit",
     "VectorStoreToolkit",
     "McpToolkit",
+    "McpConfigToolkit",
+    "get_mcp_session_manager",
+    "SkillRouterToolkit",
     "MemoryToolkit"
 ]