llms-py 2.0.20__py3-none-any.whl → 3.0.18__py3-none-any.whl

llms/extensions/skills/__init__.py

@@ -0,0 +1,130 @@
+import os
+import shutil
+from pathlib import Path
+from typing import Annotated
+
+import aiohttp
+
+from .parser import read_properties
+
+g_skills = {}
+
+
+def sanitize(name: str) -> str:
+    return name.replace(" ", "").replace("_", "").replace("-", "").lower()
+
+
+def skill(name: Annotated[str, "skill name"], file: Annotated[str | None, "skill file"] = None):
+    """Get the content of a skill or a specific file within a skill."""
+    skill = g_skills.get(name)
+
+    if not skill:
+        sanitized_name = sanitize(name)
+        for k, v in g_skills.items():
+            if sanitize(k) == sanitized_name:
+                skill = v
+                break
+
+    if not skill:
+        return f"Error: Skill {name} not found. Available skills: {', '.join(g_skills.keys())}"
+    location = skill.get("location")
+    if not location or not os.path.exists(location):
+        return f"Error: Skill {name} not found at location {location}"
+
+    if file:
+        if file.startswith(location):
+            file = file[len(location) + 1 :]
+        if not os.path.exists(os.path.join(location, file)):
+            return f"Error: File {file} not found in skill {name}. Available files: {', '.join(skill.get('files', []))}"
+        with open(os.path.join(location, file)) as f:
+            return f.read()
+
+    with open(os.path.join(location, "SKILL.md")) as f:
+        content = f.read()
+
+        files = skill.get("files")
+        if files and len(files) > 1:
+            content += "\n\n## Skill Files:\n```\n"
+            for file in files:
+                content += f"{file}\n"
+            content += "```\n"
+        return content
+
+
+def install(ctx):
+    global g_skills
+    home_skills = ctx.get_home_path(os.path.join(".agent", "skills"))
+    # if not folder exists
+    if not os.path.exists(home_skills):
+        os.makedirs(ctx.get_home_path(os.path.join(".agent")), exist_ok=True)
+        ctx.log(f"Creating initial skills folder: {home_skills}")
+        # os.makedirs(home_skills)
+        # copy ui/skills to home_skills
+        ui_skills = os.path.join(ctx.path, "ui", "skills")
+        shutil.copytree(ui_skills, home_skills)
+
+    skill_roots = {}
+
+    # add .claude skills first, so they can be overridden by .agent skills
+    if os.path.exists("~/.claude/skills"):
+        skill_roots["~/.claude/skills"] = "~/.claude/skills"
+
+    if os.path.exists(os.path.join(".claude", "skills")):
+        skill_roots[".claude/skills"] = os.path.join(".claude", "skills")
+
+    skill_roots["~/.llms/.agents"] = home_skills
+
+    if os.path.exists(os.path.join(".agent", "skills")):
+        skill_roots[".agents"] = os.path.join(".agent", "skills")
+
+    g_skills = {}
+    for group, root in skill_roots.items():
+        if not os.path.exists(root):
+            continue
+        try:
+            for entry in os.scandir(root):
+                if (
+                    entry.is_dir()
+                    and os.path.exists(os.path.join(entry.path, "SKILL.md"))
+                    or os.path.exists(os.path.join(entry.path, "skill.md"))
+                ):
+                    skill_dir = Path(entry.path).resolve()
+                    props = read_properties(skill_dir)
+
+                    # recursivly list all files in this directory
+                    files = []
+                    for file in skill_dir.glob("**/*"):
+                        if file.is_file():
+                            full_path = str(file)
+                            rel_path = full_path[len(str(skill_dir)) + 1 :]
+                            files.append(rel_path)
+
+                    skill_props = props.to_dict()
+                    skill_props.update(
+                        {
+                            "group": group,
+                            "location": str(skill_dir),
+                            "files": files,
+                        }
+                    )
+                    g_skills[props.name] = skill_props
+
+        except OSError:
+            pass
+
+    async def get_skills(request):
+        return aiohttp.web.json_response(g_skills)
+
+    ctx.add_get("", get_skills)
+
+    async def get_skill(request):
+        name = request.match_info.get("name")
+        file = request.query.get("file")
+        return aiohttp.web.Response(text=skill(name, file))
+
+    ctx.add_get("contents/{name}", get_skill)
+
+    ctx.register_tool(skill, group="core_tools")
+
+
+__install__ = install

llms/extensions/skills/errors.py

@@ -0,0 +1,25 @@
+"""Skill-related exceptions."""
+
+
+class SkillError(Exception):
+    """Base exception for all skill-related errors."""
+
+    pass
+
+
+class ParseError(SkillError):
+    """Raised when SKILL.md parsing fails."""
+
+    pass
+
+
+class ValidationError(SkillError):
+    """Raised when skill properties are invalid.
+
+    Attributes:
+        errors: List of validation error messages (may contain just one)
+    """
+
+    def __init__(self, message: str, errors: list[str] | None = None):
+        super().__init__(message)
+        self.errors = errors if errors is not None else [message]

llms/extensions/skills/models.py

@@ -0,0 +1,39 @@
+"""Data models for Agent Skills."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class SkillProperties:
+    """Properties parsed from a skill's SKILL.md frontmatter.
+
+    Attributes:
+        name: Skill name in kebab-case (required)
+        description: What the skill does and when the model should use it (required)
+        license: License for the skill (optional)
+        compatibility: Compatibility information for the skill (optional)
+        allowed_tools: Tool patterns the skill requires (optional, experimental)
+        metadata: Key-value pairs for client-specific properties (defaults to
+            empty dict; omitted from to_dict() output when empty)
+    """
+
+    name: str
+    description: str
+    license: Optional[str] = None
+    compatibility: Optional[str] = None
+    allowed_tools: Optional[str] = None
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary, excluding None values."""
+        result = {"name": self.name, "description": self.description}
+        if self.license is not None:
+            result["license"] = self.license
+        if self.compatibility is not None:
+            result["compatibility"] = self.compatibility
+        if self.allowed_tools is not None:
+            result["allowed-tools"] = self.allowed_tools
+        if self.metadata:
+            result["metadata"] = self.metadata
+        return result

llms/extensions/skills/parser.py

@@ -0,0 +1,178 @@
+"""YAML frontmatter parsing for SKILL.md files."""
+
+from pathlib import Path
+from typing import Optional
+
+from .errors import ParseError, ValidationError
+from .models import SkillProperties
+
+
+def load_yaml(content: str) -> dict:
+    """Simple YAML parser for skill frontmatter.
+
+    Supports:
+    - Key-value pairs: key: "value"
+    - Comments: # comment
+    - Simple nesting (indentation-based)
+    """
+    result = {}
+    stack = [result]
+    indents = [-1]
+    last_key = None
+
+    for line in content.splitlines():
+        # Skip empty lines or full comments
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        # Handle indent levels
+        while indent <= indents[-1]:
+            indents.pop()
+            stack.pop()
+
+        # If we have a nested block under last key
+        if indent > indents[-1] and last_key and isinstance(stack[-1], dict) and stack[-1].get(last_key) is None:
+            # This branch is tricky with the simple look-behind.
+            # Better approach: check if line is a key-value or array item
+            pass
+
+        # Parse key: value
+        if ":" in stripped:
+            key, val = stripped.split(":", 1)
+            key = key.strip()
+            val = val.strip()
+
+            # Handle quotes
+            if (val.startswith('"') and val.endswith('"')) or (val.startswith("'") and val.endswith("'")):
+                val = val[1:-1]
+            elif val.lower() == "true":
+                val = True
+            elif val.lower() == "false":
+                val = False
+            elif val == "":
+                val = None  # Could be start of nested object
+
+            current_dict = stack[-1]
+
+            if val is None:
+                # Prepare for nested object
+                new_dict = {}
+                current_dict[key] = new_dict
+                stack.append(new_dict)
+                indents.append(indent)
+            else:
+                current_dict[key] = val
+
+            last_key = key
+        else:
+            # Handle continuation lines or unknown format if needed,
+            # but for our simple use case we might error or ignore.
+            pass
+
+    return result
+
+
+def find_skill_md(skill_dir: Path) -> Optional[Path]:
+    """Find the SKILL.md file in a skill directory.
+
+    Prefers SKILL.md (uppercase) but accepts skill.md (lowercase).
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        Path to the SKILL.md file, or None if not found
+    """
+    for name in ("SKILL.md", "skill.md"):
+        path = skill_dir / name
+        if path.exists():
+            return path
+    return None
+
+
+def parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Parse YAML frontmatter from SKILL.md content.
+
+    Args:
+        content: Raw content of SKILL.md file
+
+    Returns:
+        Tuple of (metadata dict, markdown body)
+
+    Raises:
+        ParseError: If frontmatter is missing or invalid
+    """
+    if not content.startswith("---"):
+        raise ParseError("SKILL.md must start with YAML frontmatter (---)")
+
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        raise ParseError("SKILL.md frontmatter not properly closed with ---")
+
+    frontmatter_str = parts[1]
+    body = parts[2].strip()
+
+    try:
+        metadata = load_yaml(frontmatter_str)
+    except Exception as e:
+        raise ParseError(f"Invalid YAML in frontmatter: {e}") from e
+
+    if not isinstance(metadata, dict):
+        raise ParseError("SKILL.md frontmatter must be a YAML mapping")
+
+    # Clean up metadata values if necessary (simple parser already handles basics)
+    if "metadata" in metadata and isinstance(metadata["metadata"], dict):
+        metadata["metadata"] = {str(k): str(v) for k, v in metadata["metadata"].items()}
+
+    return metadata, body
+
+
+def read_properties(skill_dir: Path) -> SkillProperties:
+    """Read skill properties from SKILL.md frontmatter.
+
+    This function parses the frontmatter and returns properties.
+    It does NOT perform full validation. Use validate() for that.
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        SkillProperties with parsed metadata
+
+    Raises:
+        ParseError: If SKILL.md is missing or has invalid YAML
+        ValidationError: If required fields (name, description) are missing
+    """
+    skill_dir = Path(skill_dir)
+    skill_md = find_skill_md(skill_dir)
+
+    if skill_md is None:
+        raise ParseError(f"SKILL.md not found in {skill_dir}")
+
+    content = skill_md.read_text()
+    metadata, _ = parse_frontmatter(content)
+
+    if "name" not in metadata:
+        raise ValidationError("Missing required field in frontmatter: name")
+    if "description" not in metadata:
+        raise ValidationError("Missing required field in frontmatter: description")
+
+    name = metadata["name"]
+    description = metadata["description"]
+
+    if not isinstance(name, str) or not name.strip():
+        raise ValidationError("Field 'name' must be a non-empty string")
+    if not isinstance(description, str) or not description.strip():
+        raise ValidationError("Field 'description' must be a non-empty string")
+
+    return SkillProperties(
+        name=name.strip(),
+        description=description.strip(),
+        license=metadata.get("license"),
+        compatibility=metadata.get("compatibility"),
+        allowed_tools=metadata.get("allowed-tools"),
+        metadata=metadata.get("metadata"),
+    )