skilllite 0.1.0__py3-none-any.whl

skilllite/builtin_tools.py

@@ -0,0 +1,240 @@
+"""
+Built-in tools for SkillLite SDK.
+
+This module provides commonly needed tools like file operations
+that can be used with create_enhanced_agentic_loop.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def get_builtin_file_tools() -> List[Dict[str, Any]]:
+    """
+    Get built-in file operation tools.
+    
+    Returns:
+        List of tool definitions in OpenAI-compatible format
+    """
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": "read_file",
+                "description": "Read the content of a file",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "file_path": {
+                            "type": "string",
+                            "description": "Path to the file to read (relative or absolute)"
+                        }
+                    },
+                    "required": ["file_path"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "write_file",
+                "description": "Write content to a file. Creates the file if it doesn't exist, overwrites if it does.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "file_path": {
+                            "type": "string",
+                            "description": "Path to the file to write (relative or absolute)"
+                        },
+                        "content": {
+                            "type": "string",
+                            "description": "Content to write to the file"
+                        }
+                    },
+                    "required": ["file_path", "content"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "list_directory",
+                "description": "List files and directories in a given path",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "directory_path": {
+                            "type": "string",
+                            "description": "Path to the directory to list (relative or absolute)"
+                        },
+                        "recursive": {
+                            "type": "boolean",
+                            "description": "Whether to list recursively (default: false)",
+                            "default": False
+                        }
+                    },
+                    "required": ["directory_path"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "file_exists",
+                "description": "Check if a file or directory exists",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "file_path": {
+                            "type": "string",
+                            "description": "Path to check (relative or absolute)"
+                        }
+                    },
+                    "required": ["file_path"]
+                }
+            }
+        }
+    ]
+
+
+def execute_builtin_file_tool(tool_name: str, tool_input: Dict[str, Any]) -> str:
+    """
+    Execute a built-in file operation tool.
+    
+    Args:
+        tool_name: Name of the tool to execute
+        tool_input: Input parameters for the tool
+        
+    Returns:
+        Result of the tool execution as a string
+        
+    Raises:
+        ValueError: If tool_name is not recognized
+        Exception: If tool execution fails
+    """
+    try:
+        if tool_name == "read_file":
+            return _read_file(tool_input["file_path"])
+        elif tool_name == "write_file":
+            return _write_file(tool_input["file_path"], tool_input["content"])
+        elif tool_name == "list_directory":
+            recursive = tool_input.get("recursive", False)
+            return _list_directory(tool_input["directory_path"], recursive)
+        elif tool_name == "file_exists":
+            return _file_exists(tool_input["file_path"])
+        else:
+            raise ValueError(f"Unknown built-in tool: {tool_name}")
+    except KeyError as e:
+        return f"Error: Missing required parameter: {e}"
+    except Exception as e:
+        return f"Error executing {tool_name}: {str(e)}"
+
+
+def _read_file(file_path: str) -> str:
+    """Read file content."""
+    path = Path(file_path)
+    
+    if not path.exists():
+        return f"Error: File not found: {file_path}"
+    
+    if not path.is_file():
+        return f"Error: Path is not a file: {file_path}"
+    
+    try:
+        content = path.read_text(encoding="utf-8")
+        return f"Successfully read file: {file_path}\n\nContent:\n{content}"
+    except UnicodeDecodeError:
+        # Try reading as binary and return info
+        size = path.stat().st_size
+        return f"File {file_path} appears to be binary (size: {size} bytes). Cannot display content."
+    except Exception as e:
+        return f"Error reading file {file_path}: {str(e)}"
+
+
+def _write_file(file_path: str, content: str) -> str:
+    """Write content to file."""
+    path = Path(file_path)
+    
+    try:
+        # Create parent directories if they don't exist
+        path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Write the file
+        path.write_text(content, encoding="utf-8")
+        
+        return f"Successfully wrote to file: {file_path} ({len(content)} characters)"
+    except Exception as e:
+        return f"Error writing to file {file_path}: {str(e)}"
+
+
+def _list_directory(directory_path: str, recursive: bool = False) -> str:
+    """List directory contents."""
+    path = Path(directory_path)
+    
+    if not path.exists():
+        return f"Error: Directory not found: {directory_path}"
+    
+    if not path.is_dir():
+        return f"Error: Path is not a directory: {directory_path}"
+    
+    try:
+        items = []
+        
+        if recursive:
+            # Recursive listing
+            for item in path.rglob("*"):
+                rel_path = item.relative_to(path)
+                item_type = "dir" if item.is_dir() else "file"
+                items.append(f"{item_type}: {rel_path}")
+        else:
+            # Non-recursive listing
+            for item in path.iterdir():
+                item_type = "dir" if item.is_dir() else "file"
+                items.append(f"{item_type}: {item.name}")
+        
+        if not items:
+            return f"Directory is empty: {directory_path}"
+        
+        items.sort()
+        result = f"Contents of {directory_path}:\n" + "\n".join(items)
+        return result
+    except Exception as e:
+        return f"Error listing directory {directory_path}: {str(e)}"
+
+
+def _file_exists(file_path: str) -> str:
+    """Check if file exists."""
+    path = Path(file_path)
+    
+    if path.exists():
+        if path.is_file():
+            size = path.stat().st_size
+            return f"File exists: {file_path} (size: {size} bytes)"
+        elif path.is_dir():
+            return f"Directory exists: {file_path}"
+        else:
+            return f"Path exists but is neither file nor directory: {file_path}"
+    else:
+        return f"Path does not exist: {file_path}"
+
+
+def create_builtin_tool_executor():
+    """
+    Create an executor function for built-in tools.
+    
+    Returns:
+        Executor function that can be passed to create_enhanced_agentic_loop
+    """
+    builtin_tool_names = {"read_file", "write_file", "list_directory", "file_exists"}
+    
+    def executor(tool_input: Dict[str, Any]) -> str:
+        """Execute built-in tools."""
+        tool_name = tool_input.get("tool_name")
+        
+        if tool_name not in builtin_tool_names:
+            raise ValueError(f"Not a built-in tool: {tool_name}")
+        
+        return execute_builtin_file_tool(tool_name, tool_input)
+    
+    return executor

skilllite/cli.py

@@ -0,0 +1,217 @@
+"""
+Command-line interface for skilllite.
+
+Provides commands for managing the skillbox binary, similar to
+how Playwright provides `playwright install` for browser management.
+
+Usage:
+    skilllite install     # Download and install the sandbox binary
+    skilllite uninstall   # Remove the installed binary
+    skilllite status      # Show installation status
+    skilllite version     # Show version information
+    skilllite mcp         # Start MCP server
+"""
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .sandbox.skillbox import (
+    BINARY_VERSION,
+    get_platform,
+    install,
+    is_installed,
+    get_installed_version,
+    uninstall,
+)
+
+
+def print_status() -> None:
+    """Print installation status."""
+    from .sandbox.skillbox import find_binary, get_binary_path
+    
+    print("SkillLite Installation Status")
+    print("=" * 40)
+    
+    if is_installed():
+        version = get_installed_version()
+        print(f"✓ skillbox is installed (v{version})")
+        print(f"  Location: {get_binary_path()}")
+    else:
+        binary = find_binary()
+        if binary:
+            print(f"✓ skillbox found at: {binary}")
+        else:
+            print("✗ skillbox is not installed")
+            print("  Install with: skilllite install")
+
+def cmd_install(args: argparse.Namespace) -> int:
+    """Install the skillbox binary."""
+    try:
+        install(
+            version=args.version,
+            force=args.force,
+            show_progress=not args.quiet
+        )
+        return 0
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    """Uninstall the skillbox binary."""
+    try:
+        uninstall()
+        return 0
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """Show installation status."""
+    try:
+        print_status()
+        return 0
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+def cmd_version(args: argparse.Namespace) -> int:
+    """Show version information."""
+    print(f"skilllite Python SDK: v{__version__}")
+    print(f"skillbox binary (bundled): v{BINARY_VERSION}")
+    
+    installed_version = get_installed_version()
+    if installed_version:
+        print(f"skillbox binary (installed): v{installed_version}")
+    else:
+        print("skillbox binary (installed): not installed")
+    
+    try:
+        plat = get_platform()
+        print(f"Platform: {plat}")
+    except RuntimeError as e:
+        print(f"Platform: {e}")
+    
+    return 0
+
+def cmd_mcp_server(args: argparse.Namespace) -> int:
+    """Start MCP server."""
+    try:
+        import asyncio
+        from .mcp.server import main as mcp_main
+        
+        asyncio.run(mcp_main())
+        return 0
+    except ImportError as e:
+        print("Error: MCP integration not available", file=sys.stderr)
+        print("Please install it with: pip install skilllite[mcp]", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\nMCP server stopped by user", file=sys.stderr)
+        return 0
+    except Exception as e:
+        import traceback
+        print(f"Error starting MCP server: {e}", file=sys.stderr)
+        traceback.print_exc()
+        return 1
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="skilllite",
+        description="SkillLite - A lightweight Skills execution engine with LLM integration",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  skilllite install          Install the sandbox binary
+  skilllite install --force  Force reinstall
+  skilllite status           Check installation status
+  skilllite uninstall        Remove the binary
+  skilllite mcp              Start MCP server (requires pip install skilllite[mcp])
+
+For more information, visit: https://github.com/skilllite/skilllite
+        """
+    )
+    
+    parser.add_argument(
+        "-V", "--version",
+        action="store_true",
+        help="Show version information"
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # install command
+    install_parser = subparsers.add_parser(
+        "install",
+        help="Download and install the skillbox sandbox binary"
+    )
+    install_parser.add_argument(
+        "--version",
+        dest="version",
+        default=None,
+        help=f"Version to install (default: {BINARY_VERSION})"
+    )
+    install_parser.add_argument(
+        "--force", "-f",
+        action="store_true",
+        help="Force reinstall even if already installed"
+    )
+    install_parser.add_argument(
+        "--quiet", "-q",
+        action="store_true",
+        help="Suppress progress output"
+    )
+    install_parser.set_defaults(func=cmd_install)
+    
+    # uninstall command
+    uninstall_parser = subparsers.add_parser(
+        "uninstall",
+        help="Remove the installed skillbox binary"
+    )
+    uninstall_parser.set_defaults(func=cmd_uninstall)
+    
+    # status command
+    status_parser = subparsers.add_parser(
+        "status",
+        help="Show installation status"
+    )
+    status_parser.set_defaults(func=cmd_status)
+    
+    # version command (alternative to -V)
+    version_parser = subparsers.add_parser(
+        "version",
+        help="Show version information"
+    )
+    version_parser.set_defaults(func=cmd_version)
+    
+    # mcp command
+    mcp_parser = subparsers.add_parser(
+        "mcp",
+        help="Start MCP server for SkillLite"
+    )
+    mcp_parser.set_defaults(func=cmd_mcp_server)
+    
+    return parser
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Main entry point for the CLI."""
+    parser = create_parser()
+    args = parser.parse_args(argv)
+    
+    # Handle -V/--version flag
+    if args.version:
+        return cmd_version(args)
+    
+    # Handle no command
+    if not args.command:
+        parser.print_help()
+        return 0
+    
+    # Execute the command
+    return args.func(args)
+
+if __name__ == "__main__":
+    sys.exit(main())

skilllite/core/__init__.py

@@ -0,0 +1,65 @@
+"""
+SkillLite Core - Core execution engine and data structures.
+
+This module contains the essential components that should never be modified
+by external tools or AI assistants without explicit user permission.
+
+Core Components:
+- SkillManager: Main interface for managing skills (facade)
+- SkillRegistry: Skill registration and discovery
+- ToolBuilder: Tool definition generation and schema inference
+- PromptBuilder: System prompt context generation
+- ToolCallHandler: LLM response handling and tool execution
+- SkillExecutor: Executes skills using the skillbox binary
+- AgenticLoop: Handles LLM-tool interaction loops
+- SkillInfo: Information container for skills
+- ToolDefinition/ToolResult: Tool protocol adapters
+- ExecutionResult: Result of skill execution
+
+These components are protected and should only be modified by:
+1. The original maintainer
+2. Explicit user requests
+3. Critical bug fixes
+
+All other functionality (CLI, quick start, utilities, etc.) should be
+implemented in modules outside this core directory.
+"""
+
+from .manager import SkillManager
+from .executor import SkillExecutor, ExecutionResult
+from .loops import AgenticLoop, AgenticLoopClaudeNative, ApiFormat
+from .skill_info import SkillInfo
+from .tools import ToolDefinition, ToolUseRequest, ToolResult, ToolFormat
+from .metadata import SkillMetadata, NetworkPolicy, parse_skill_metadata
+from .registry import SkillRegistry
+from .tool_builder import ToolBuilder
+from .prompt_builder import PromptBuilder
+from .handler import ToolCallHandler
+
+__all__ = [
+    # Core Management (Facade)
+    "SkillManager",
+    # Modular Components
+    "SkillRegistry",
+    "ToolBuilder",
+    "PromptBuilder",
+    "ToolCallHandler",
+    # Skill Info
+    "SkillInfo",
+    "SkillMetadata",
+    "NetworkPolicy",
+    # Execution
+    "SkillExecutor",
+    "ExecutionResult",
+    # Loops
+    "AgenticLoop",
+    "AgenticLoopClaudeNative",
+    "ApiFormat",
+    # Tools
+    "ToolDefinition",
+    "ToolUseRequest",
+    "ToolResult",
+    "ToolFormat",
+    # Utilities
+    "parse_skill_metadata",
+]

skilllite/core/executor.py

@@ -0,0 +1,182 @@
+"""
+Skill executor - interfaces with the Rust skillbox binary.
+
+This module provides a thin wrapper around SkillboxExecutor for backward compatibility.
+All actual execution logic is delegated to the sandbox.skillbox.executor module.
+
+This is a CORE module - do not modify without explicit permission.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..sandbox.base import ExecutionResult
+from ..sandbox.skillbox.executor import SkillboxExecutor
+
+__all__ = ['SkillExecutor', 'ExecutionResult']
+
+
+class SkillExecutor:
+    """
+    Executes skills using the skillbox binary.
+    
+    This class provides a Python interface to the Rust-based sandbox executor.
+    Supports both traditional skill execution (via entry_point in SKILL.md) and
+    direct script execution (via exec command).
+    
+    This is a thin wrapper around SkillboxExecutor for backward compatibility.
+    All execution logic is delegated to SkillboxExecutor.
+    """
+    
+    def __init__(
+        self,
+        binary_path: Optional[str] = None,
+        cache_dir: Optional[str] = None,
+        allow_network: bool = False,
+        enable_sandbox: bool = True,
+        execution_timeout: Optional[int] = None,
+        max_memory_mb: Optional[int] = None,
+        sandbox_level: Optional[str] = None,
+        auto_install: bool = False
+    ):
+        """
+        Initialize the executor.
+        
+        Args:
+            binary_path: Path to the skillbox binary. If None, auto-detect.
+            cache_dir: Directory for caching virtual environments.
+            allow_network: Whether to allow network access by default.
+            enable_sandbox: Whether to enable sandbox protection (default: True).
+            execution_timeout: Skill execution timeout in seconds (default: 120).
+            max_memory_mb: Maximum memory limit in MB (default: 512).
+            sandbox_level: Sandbox security level (1/2/3, default from env or 3).
+            auto_install: Automatically download and install binary if not found.
+        """
+        self._executor = SkillboxExecutor(
+            binary_path=binary_path,
+            cache_dir=cache_dir,
+            allow_network=allow_network,
+            enable_sandbox=enable_sandbox,
+            execution_timeout=execution_timeout,
+            max_memory_mb=max_memory_mb,
+            sandbox_level=sandbox_level,
+            auto_install=auto_install
+        )
+    
+    @property
+    def binary_path(self) -> str:
+        """Path to the skillbox binary."""
+        return self._executor.binary_path
+    
+    @property
+    def cache_dir(self) -> Optional[str]:
+        """Directory for caching virtual environments."""
+        return self._executor.cache_dir
+    
+    @property
+    def allow_network(self) -> bool:
+        """Whether network access is allowed by default."""
+        return self._executor.allow_network
+    
+    @property
+    def enable_sandbox(self) -> bool:
+        """Whether sandbox protection is enabled."""
+        return self._executor.enable_sandbox
+    
+    @property
+    def execution_timeout(self) -> int:
+        """Skill execution timeout in seconds."""
+        return self._executor.execution_timeout
+    
+    @property
+    def max_memory_mb(self) -> int:
+        """Maximum memory limit in MB."""
+        return self._executor.max_memory_mb
+    
+    @property
+    def sandbox_level(self) -> str:
+        """Sandbox security level (1/2/3)."""
+        return self._executor.sandbox_level
+    
+    @property
+    def is_available(self) -> bool:
+        """Check if skillbox is available and ready to use."""
+        return self._executor.is_available
+    
+    @property
+    def name(self) -> str:
+        """Return the name of this sandbox implementation."""
+        return self._executor.name
+    
+    def execute(
+        self,
+        skill_dir: Path,
+        input_data: Dict[str, Any],
+        allow_network: Optional[bool] = None,
+        timeout: Optional[int] = None,
+        entry_point: Optional[str] = None,
+        enable_sandbox: Optional[bool] = None
+    ) -> ExecutionResult:
+        """
+        Execute a skill with the given input.
+        
+        Args:
+            skill_dir: Path to the skill directory
+            input_data: Input data for the skill
+            allow_network: Override default network setting
+            timeout: Execution timeout in seconds
+            entry_point: Optional specific script to execute (e.g., "scripts/init_skill.py").
+                        If provided, uses exec_script instead of run command.
+            enable_sandbox: Override default sandbox setting
+            
+        Returns:
+            ExecutionResult with the output or error
+        """
+        return self._executor.execute(
+            skill_dir=skill_dir,
+            input_data=input_data,
+            allow_network=allow_network,
+            timeout=timeout,
+            entry_point=entry_point,
+            enable_sandbox=enable_sandbox
+        )
+    
+    def exec_script(
+        self,
+        skill_dir: Path,
+        script_path: str,
+        input_data: Dict[str, Any],
+        args: Optional[list] = None,
+        allow_network: Optional[bool] = None,
+        timeout: Optional[int] = None,
+        enable_sandbox: Optional[bool] = None
+    ) -> ExecutionResult:
+        """
+        Execute a specific script directly.
+        
+        This method allows executing any script in the skill directory without
+        requiring an entry_point in SKILL.md. Useful for skills with multiple
+        scripts or prompt-only skills with helper scripts.
+        
+        Args:
+            skill_dir: Path to the skill directory
+            script_path: Relative path to the script (e.g., "scripts/init_skill.py")
+            input_data: Input data for the script. For CLI scripts using argparse,
+                       this will be automatically converted to command line arguments.
+            args: Optional command line arguments list (overrides auto-conversion)
+            allow_network: Override default network setting
+            timeout: Execution timeout in seconds
+            enable_sandbox: Override default sandbox setting
+            
+        Returns:
+            ExecutionResult with the output or error
+        """
+        return self._executor.exec_script(
+            skill_dir=skill_dir,
+            script_path=script_path,
+            input_data=input_data,
+            args=args,
+            allow_network=allow_network,
+            timeout=timeout,
+            enable_sandbox=enable_sandbox
+        )