kweaver-dolphin 0.1.0__py3-none-any.whl

dolphin/lib/skillkits/resource/models/skill_config.py

@@ -0,0 +1,109 @@
+"""Configuration models for ResourceSkillkit.
+
+This module contains configuration dataclasses for ResourceSkillkit settings.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+from pathlib import Path
+
+
+# Default values as module constants to avoid duplication
+_DEFAULT_DIRECTORIES = ["./skills"]
+_DEFAULT_MAX_SKILL_SIZE_MB = 8
+_DEFAULT_MAX_CONTENT_TOKENS = 8000
+_DEFAULT_CACHE_TTL_SECONDS = 300
+_DEFAULT_MAX_CACHE_SIZE = 100
+_DEFAULT_MAX_SCAN_DEPTH = 6
+_DEFAULT_ALLOWED_EXTENSIONS = [
+    ".py", ".sh", ".js", ".ts", ".md", ".txt", ".json", ".yaml", ".yml"
+]
+
+
+@dataclass
+class ResourceSkillConfig:
+    """Configuration for ResourceSkillkit.
+
+    Attributes:
+        enabled: Whether ResourceSkillkit is enabled
+        directories: List of directories to scan for skills (in priority order)
+        max_skill_size_mb: Maximum size of a single skill package in MB
+        max_content_tokens: Maximum tokens to return in a single load
+        cache_ttl_seconds: TTL for metadata cache in seconds
+        max_cache_size: Maximum number of items in cache
+        max_scan_depth: Maximum directory depth when scanning for skills
+        allowed_extensions: File extensions allowed for resource files
+    """
+
+    enabled: bool = True
+    directories: List[str] = field(default_factory=lambda: list(_DEFAULT_DIRECTORIES))
+    max_skill_size_mb: int = _DEFAULT_MAX_SKILL_SIZE_MB
+    max_content_tokens: int = _DEFAULT_MAX_CONTENT_TOKENS
+    cache_ttl_seconds: int = _DEFAULT_CACHE_TTL_SECONDS
+    max_cache_size: int = _DEFAULT_MAX_CACHE_SIZE
+    max_scan_depth: int = _DEFAULT_MAX_SCAN_DEPTH
+    allowed_extensions: List[str] = field(
+        default_factory=lambda: list(_DEFAULT_ALLOWED_EXTENSIONS)
+    )
+
+    @classmethod
+    def from_dict(cls, config_dict: dict) -> "ResourceSkillConfig":
+        """Create config from dictionary (e.g., from YAML config).
+
+        Args:
+            config_dict: Dictionary with configuration values
+
+        Returns:
+            ResourceSkillConfig instance
+        """
+        resource_config = config_dict.get("resource_skills", {})
+
+        limits = resource_config.get("limits", {})
+
+        return cls(
+            enabled=resource_config.get("enabled", True),
+            directories=resource_config.get("directories", _DEFAULT_DIRECTORIES),
+            max_skill_size_mb=limits.get("max_skill_size_mb", _DEFAULT_MAX_SKILL_SIZE_MB),
+            max_content_tokens=limits.get("max_content_tokens", _DEFAULT_MAX_CONTENT_TOKENS),
+            cache_ttl_seconds=resource_config.get("cache_ttl_seconds", _DEFAULT_CACHE_TTL_SECONDS),
+            max_cache_size=resource_config.get("max_cache_size", _DEFAULT_MAX_CACHE_SIZE),
+            max_scan_depth=resource_config.get("max_scan_depth", _DEFAULT_MAX_SCAN_DEPTH),
+            allowed_extensions=resource_config.get("allowed_extensions", _DEFAULT_ALLOWED_EXTENSIONS),
+        )
+
+    def get_resolved_directories(self, base_path: Optional[Path] = None) -> List[Path]:
+        """Resolve directory paths, expanding ~ and making absolute.
+
+        Args:
+            base_path: Optional base path for resolving relative paths
+
+        Returns:
+            List of resolved absolute Path objects
+        """
+        resolved = []
+        for dir_str in self.directories:
+            path = Path(dir_str).expanduser()
+            if not path.is_absolute():
+                if base_path:
+                    path = base_path / path
+                else:
+                    path = Path.cwd() / path
+            resolved.append(path.resolve())
+        return resolved
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary representation.
+
+        Returns:
+            Dictionary with all configuration fields
+        """
+        return {
+            "enabled": self.enabled,
+            "directories": self.directories,
+            "max_skill_size_mb": self.max_skill_size_mb,
+            "max_content_tokens": self.max_content_tokens,
+            "cache_ttl_seconds": self.cache_ttl_seconds,
+            "max_cache_size": self.max_cache_size,
+            "max_scan_depth": self.max_scan_depth,
+            "allowed_extensions": self.allowed_extensions,
+        }

dolphin/lib/skillkits/resource/models/skill_meta.py

@@ -0,0 +1,127 @@
+"""Data models for ResourceSkillkit.
+
+This module contains the SkillMeta and SkillContent dataclasses for
+representing skill metadata (Level 1) and full content (Level 2).
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+
+
+@dataclass
+class SkillMeta:
+    """Level 1 metadata - lightweight skill information.
+
+    This represents the minimal metadata loaded for each skill,
+    used for system prompt injection (~100 tokens per skill).
+
+    Attributes:
+        name: Unique skill identifier
+        description: Brief description of what the skill does
+        base_path: Absolute path to the skill directory
+        version: Optional semantic version string
+        tags: Optional list of categorization tags
+    """
+
+    name: str
+    description: str
+    base_path: str
+    version: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+
+    def to_prompt_entry(self) -> str:
+        """Generate a markdown entry for system prompt injection.
+
+        Returns:
+            Formatted markdown string for this skill's metadata
+        """
+        return f"### {self.name}\n{self.description}"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation.
+
+        Returns:
+            Dictionary with all metadata fields
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "base_path": self.base_path,
+            "version": self.version,
+            "tags": self.tags,
+        }
+
+
+@dataclass
+class SkillContent:
+    """Level 2 full content - complete SKILL.md content.
+
+    This represents the fully loaded skill content including
+    the YAML frontmatter and markdown body (~1500 tokens).
+
+    Attributes:
+        frontmatter: Parsed YAML frontmatter as dictionary
+        body: The markdown content after frontmatter
+        available_scripts: List of script file paths in scripts/ directory
+        available_references: List of reference file paths in references/ directory
+    """
+
+    frontmatter: Dict[str, Any]
+    body: str
+    available_scripts: List[str] = field(default_factory=list)
+    available_references: List[str] = field(default_factory=list)
+
+    def get_name(self) -> str:
+        """Get skill name from frontmatter.
+
+        Returns:
+            The skill name, or empty string if not found
+        """
+        return self.frontmatter.get("name", "")
+
+    def get_description(self) -> str:
+        """Get skill description from frontmatter.
+
+        Returns:
+            The skill description, or empty string if not found
+        """
+        return self.frontmatter.get("description", "")
+
+    def get_full_content(self) -> str:
+        """Get the complete content for Level 2 loading.
+
+        This includes the markdown body plus a list of available
+        resources that can be loaded via Level 3.
+
+        Returns:
+            Complete formatted content string
+        """
+        content_parts = [self.body]
+
+        if self.available_scripts or self.available_references:
+            content_parts.append("\n\n## Available Resources\n")
+
+            if self.available_scripts:
+                content_parts.append("\n**Scripts:**")
+                for script in self.available_scripts:
+                    content_parts.append(f"\n- `{script}`")
+
+            if self.available_references:
+                content_parts.append("\n\n**References:**")
+                for ref in self.available_references:
+                    content_parts.append(f"\n- `{ref}`")
+
+        return "".join(content_parts)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation.
+
+        Returns:
+            Dictionary with all content fields
+        """
+        return {
+            "frontmatter": self.frontmatter,
+            "body": self.body,
+            "available_scripts": self.available_scripts,
+            "available_references": self.available_references,
+        }

dolphin/lib/skillkits/resource/resource_skillkit.py

@@ -0,0 +1,393 @@
+"""ResourceSkillkit - Claude Skill format support for Dolphin.
+
+This module implements ResourceSkillkit, a Skillkit type that supports
+resource/guidance skills in Claude Skill format (SKILL.md).
+
+Key features:
+- Progressive loading (Level 1/2/3)
+- Prefix Cache optimization
+- History bucket persistence
+- Local-first design
+"""
+
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+
+from dolphin.core.common.constants import PIN_MARKER
+from dolphin.core.skill.skill_function import SkillFunction
+from dolphin.core.skill.skillkit import Skillkit
+from dolphin.core.logging.logger import get_logger
+
+from .models.skill_meta import SkillMeta, SkillContent
+from .models.skill_config import ResourceSkillConfig
+from .skill_loader import SkillLoader, truncate_content
+from .skill_cache import SkillMetaCache, SkillContentCache
+from .skill_validator import validate_skill_name
+
+logger = get_logger("resource_skillkit")
+
+
+class ResourceSkillkit(Skillkit):
+    """ResourceSkillkit - Support for Claude Skill format resources.
+
+    This Skillkit type provides support for resource/guidance skills
+    that teach LLMs how to solve complex problems. Unlike execution
+    skillkits (SQL, Python, MCP), ResourceSkillkit loads knowledge
+    resources in Claude Skill format (SKILL.md).
+
+    Progressive Loading:
+    - Level 1: Metadata (~100 tokens) - auto-injected to system prompt
+    - Level 2: Full SKILL.md content (~1500 tokens) - via tool call
+    - Level 3: Resource files (scripts/references) - on-demand
+
+    Prefix Cache Optimization:
+    - Level 1 metadata is fixed in system prompt
+    - Level 2 content enters _history bucket via tool response
+    - System prompt remains stable for cache hits
+
+    Example usage:
+        ```python
+        config = ResourceSkillConfig(
+            directories=["./skills", "~/.dolphin/skills"]
+        )
+        skillkit = ResourceSkillkit(config)
+        skillkit.initialize()
+
+        # Get metadata prompt for system injection
+        metadata_prompt = skillkit.getMetadataPrompt()
+
+        # Load full skill content (returns tool response)
+        content = skillkit.load_skill("data-pipeline")
+        ```
+    """
+
+    def __init__(self, config: Optional[ResourceSkillConfig] = None):
+        """Initialize ResourceSkillkit.
+
+        Args:
+            config: Optional configuration, uses defaults if not provided
+        """
+        super().__init__()
+        self.config = config or ResourceSkillConfig()
+        self.loader = SkillLoader(self.config)
+        self._meta_cache = SkillMetaCache(
+            ttl_seconds=self.config.cache_ttl_seconds,
+            max_size=self.config.max_cache_size,
+        )
+        self._content_cache = SkillContentCache(
+            ttl_seconds=self.config.cache_ttl_seconds * 2,
+            max_size=max(1, self.config.max_cache_size // 2),
+        )
+        self._initialized = False
+        self._skills_meta: Dict[str, SkillMeta] = {}
+        self._base_path: Optional[Path] = None
+
+    def setGlobalConfig(self, globalConfig) -> None:
+        super().setGlobalConfig(globalConfig)
+        resource_skills_cfg = getattr(globalConfig, "resource_skills", None)
+        if not isinstance(resource_skills_cfg, dict):
+            return
+
+        try:
+            new_config = ResourceSkillConfig.from_dict(
+                {"resource_skills": resource_skills_cfg}
+            )
+        except Exception as e:
+            logger.warning(f"Failed to parse resource_skills config: {e}")
+            return
+
+        self.config = new_config
+        self.loader = SkillLoader(self.config)
+        self._meta_cache = SkillMetaCache(
+            ttl_seconds=self.config.cache_ttl_seconds,
+            max_size=self.config.max_cache_size,
+        )
+        self._content_cache = SkillContentCache(
+            ttl_seconds=self.config.cache_ttl_seconds * 2,
+            max_size=max(1, self.config.max_cache_size // 2),
+        )
+        # Clear old state to avoid stale data
+        self._skills_meta.clear()
+        self._initialized = False
+
+        # Get base_dir from GlobalConfig to resolve relative paths
+        base_dir = getattr(globalConfig, "base_dir", None)
+        if base_dir:
+            from pathlib import Path
+            self._base_path = Path(base_dir)
+
+    def _ensure_initialized(self) -> None:
+        """Ensure the skillkit has scanned and loaded Level 1 metadata."""
+        if self._initialized:
+            return
+        self.initialize(self._base_path)
+
+    def getName(self) -> str:
+        """Get the name of this skillkit.
+
+        Returns:
+            The skillkit name
+        """
+        return "resource_skillkit"
+
+    def initialize(self, base_path: Optional[Path] = None) -> None:
+        """Initialize the skillkit by scanning for available skills.
+
+        This scans all configured directories and loads Level 1 metadata
+        for each valid skill found.
+
+        Args:
+            base_path: Optional base path for resolving relative directories
+        """
+        self._base_path = base_path
+        self._skills_meta.clear()
+        self._meta_cache.clear()
+
+        if not self.config.enabled:
+            logger.info("ResourceSkillkit is disabled")
+            self._initialized = True
+            return
+
+        # Scan directories and load metadata
+        metas = self.loader.scan_directories(base_path)
+
+        for meta in metas:
+            self._skills_meta[meta.name] = meta
+            self._meta_cache.set(meta.name, meta)
+
+        logger.info(f"Initialized ResourceSkillkit with {len(self._skills_meta)} skills")
+        self._initialized = True
+
+    def _createSkills(self) -> List[SkillFunction]:
+        """Create the list of skill functions provided by this skillkit.
+
+        Note: _list_resource_skills is NOT exposed as a tool because
+        Level 1 metadata is auto-injected into system prompt via
+        get_metadata_prompt(). LLM sees available skills upfront.
+
+        Returns:
+            List of SkillFunction objects for Level 2/3 loading
+        """
+        return [
+            SkillFunction(self._load_resource_skill),
+            SkillFunction(self._load_skill_resource),
+        ]
+
+    def get_metadata_prompt(self) -> str:
+        """Generate fixed metadata prompt for system injection (Level 1).
+
+        This generates the Level 1 metadata content that is automatically
+        injected into the system prompt. The content is stable and
+        sorted alphabetically to ensure Prefix Cache compatibility.
+
+        This overrides the base Skillkit.get_metadata_prompt() method.
+
+        Returns:
+            Markdown-formatted metadata prompt with available resource skills.
+            Always includes the section header, even when no skills are available.
+        """
+        self._ensure_initialized()
+
+        parts = ["## Available Resource Skills\n"]
+
+        if not self._skills_meta:
+            # Always include the section header to prevent hallucination
+            # when user's system prompt references this section
+            parts.append("\n_No resource skills are currently available._\n")
+            return "".join(parts)
+
+        # Sort by name for stable ordering (Prefix Cache)
+        for name in sorted(self._skills_meta.keys()):
+            meta = self._skills_meta[name]
+            parts.append(f"\n{meta.to_prompt_entry()}\n")
+
+        return "".join(parts)
+
+    def load_skill(self, name: str) -> str:
+        """Load Level 2 full content for a skill.
+
+        This is the internal method called by _load_resource_skill.
+        The returned content enters _history bucket as tool response.
+
+        Args:
+            name: The skill name to load
+
+        Returns:
+            Full SKILL.md content or error message
+        """
+        self._ensure_initialized()
+
+        # Validate name
+        is_valid, error = validate_skill_name(name)
+        if not is_valid:
+            return f"Error: {error}"
+
+        # Check if skill exists
+        if name not in self._skills_meta:
+            available = sorted(self._skills_meta.keys())
+            return (
+                f"Error: Skill '{name}' not found.\n"
+                f"Available skills: {', '.join(available) if available else 'none'}"
+            )
+
+        # Check content cache
+        cached_content = self._content_cache.get(name)
+        meta = self._skills_meta[name]
+        skill_dir = Path(meta.base_path)
+        
+        # Build path info header to help Agent know where to execute commands
+        path_info = f"**Skill Root Directory:** `{skill_dir}`\n\n---\n\n"
+        
+        if cached_content:
+            full_content = path_info + cached_content.get_full_content()
+            return truncate_content(full_content, self.config.max_content_tokens)
+
+        # Load from disk
+        content = self.loader.load_content(skill_dir)
+        if content is None:
+            return f"Error: Failed to load content for skill '{name}'"
+
+        # Cache the content
+        self._content_cache.set(name, content)
+
+        # Truncate if necessary - include path info at the beginning
+        full_content = path_info + content.get_full_content()
+        return truncate_content(full_content, self.config.max_content_tokens)
+
+    def load_resource(self, skill_name: str, resource_path: str) -> str:
+        """Load Level 3 resource file content.
+
+        This is the internal method called by _load_skill_resource.
+        The returned content is temporary (scratchpad).
+
+        Args:
+            skill_name: The skill name
+            resource_path: Relative path to resource file
+
+        Returns:
+            Resource file content or error message
+        """
+        self._ensure_initialized()
+
+        # Validate skill name
+        is_valid, error = validate_skill_name(skill_name)
+        if not is_valid:
+            return f"Error: {error}"
+
+        # Check if skill exists
+        if skill_name not in self._skills_meta:
+            available = sorted(self._skills_meta.keys())
+            return (
+                f"Error: Skill '{skill_name}' not found.\n"
+                f"Available skills: {', '.join(available) if available else 'none'}"
+            )
+
+        # Load resource
+        meta = self._skills_meta[skill_name]
+        skill_dir = Path(meta.base_path)
+
+        content, error = self.loader.load_resource(skill_dir, resource_path)
+        if error:
+            return f"Error: {error}"
+
+        # Format with file info header
+        return f"# {resource_path}\n\n```\n{content}\n```"
+
+    def clear_caches(self) -> None:
+        """Clear all internal caches.
+
+        This forces a reload from disk on next access.
+        """
+        self._meta_cache.clear()
+        self._content_cache.clear()
+
+    def get_available_skills(self) -> List[str]:
+        """Get list of available skill names.
+
+        Returns:
+            Sorted list of skill names
+        """
+        self._ensure_initialized()
+        return sorted(self._skills_meta.keys())
+
+    def get_skill_meta(self, name: str) -> Optional[SkillMeta]:
+        """Get metadata for a specific skill.
+
+        Args:
+            name: The skill name
+
+        Returns:
+            SkillMeta if found, None otherwise
+        """
+        return self._skills_meta.get(name)
+
+    # =====================================
+    # Tool Functions (exposed to LLM)
+    # =====================================
+
+    def _load_resource_skill(self, skill_name: str, **kwargs) -> str:
+        """Load the full instructions for a resource skill.
+
+        Loads the complete SKILL.md content for the specified skill.
+        The loaded content will be available in conversation history
+        for subsequent turns.
+
+        Args:
+            skill_name (str): Name of the skill to load
+
+        Returns:
+            str: Full skill content including instructions and available resources
+        """
+        content = self.load_skill(skill_name)
+        if content.startswith(PIN_MARKER):
+            return content
+        return f"{PIN_MARKER}\n{content}"
+
+    def _load_skill_resource(self, skill_name: str, resource_path: str, **kwargs) -> str:
+        """Load a specific resource file from a skill package.
+
+        Loads content from scripts/ or references/ directories within
+        a skill package. The resource path should be relative to the
+        skill directory (e.g., "scripts/etl.py").
+
+        Note: Level 3 resources are designed to be ephemeral (single-turn only).
+        Unlike Level 2 SKILL.md content, these resources do NOT use PIN_MARKER
+        and will not be persisted to history. They can be reloaded on-demand.
+
+        Args:
+            skill_name (str): Name of the skill
+            resource_path (str): Relative path to the resource file
+
+        Returns:
+            str: Resource file content
+        """
+        # Level 3: No PIN_MARKER - content goes to scratchpad, discarded after turn
+        return self.load_resource(skill_name, resource_path)
+
+    # =====================================
+    # Utility Methods
+    # =====================================
+
+    def refresh(self) -> int:
+        """Refresh the skill list by rescanning directories.
+
+        Returns:
+            Number of skills found
+        """
+        self.initialize(self._base_path)
+        return len(self._skills_meta)
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics about the skillkit.
+
+        Returns:
+            Dictionary with statistics
+        """
+        return {
+            "enabled": self.config.enabled,
+            "initialized": self._initialized,
+            "skill_count": len(self._skills_meta),
+            "meta_cache": self._meta_cache.stats(),
+            "content_cache": self._content_cache.stats(),
+            "directories": self.config.directories,
+        }