empathy-framework 4.6.6__py3-none-any.whl → 4.7.0__py3-none-any.whl

empathy_llm_toolkit/commands/models.py

@@ -0,0 +1,231 @@
+"""Command Configuration Models
+
+Data models for command definitions loaded from markdown files.
+
+Architectural patterns inspired by everything-claude-code by Affaan Mustafa.
+See: https://github.com/affaan-m/everything-claude-code (MIT License)
+See: ACKNOWLEDGMENTS.md for full attribution.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class CommandCategory(str, Enum):
+    """Categories for commands."""
+
+    WORKFLOW = "workflow"  # Multi-step workflows
+    GIT = "git"  # Git operations
+    TEST = "test"  # Testing related
+    DOCS = "docs"  # Documentation
+    SECURITY = "security"  # Security analysis
+    PERFORMANCE = "performance"  # Performance tools
+    LEARNING = "learning"  # Pattern learning
+    CONTEXT = "context"  # Context management
+    UTILITY = "utility"  # General utilities
+
+
+@dataclass
+class CommandMetadata:
+    """Metadata for a command extracted from YAML frontmatter.
+
+    Example frontmatter:
+        ---
+        name: compact
+        description: Strategic context compaction
+        category: context
+        aliases: [comp, save-state]
+        hooks:
+          pre: PreCompact
+          post: PostCompact
+        requires_user_id: true
+        ---
+    """
+
+    name: str
+    description: str = ""
+    category: CommandCategory = CommandCategory.UTILITY
+    aliases: list[str] = field(default_factory=list)
+    hooks: dict[str, str] = field(default_factory=dict)
+    requires_user_id: bool = False
+    requires_context: bool = False
+    tags: list[str] = field(default_factory=list)
+    author: str = ""
+    version: str = "1.0"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "category": self.category.value,
+            "aliases": self.aliases,
+            "hooks": self.hooks,
+            "requires_user_id": self.requires_user_id,
+            "requires_context": self.requires_context,
+            "tags": self.tags,
+            "author": self.author,
+            "version": self.version,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CommandMetadata:
+        """Create from dictionary."""
+        category_str = data.get("category", "utility")
+        try:
+            category = CommandCategory(category_str)
+        except ValueError:
+            category = CommandCategory.UTILITY
+
+        return cls(
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            category=category,
+            aliases=data.get("aliases", []),
+            hooks=data.get("hooks", {}),
+            requires_user_id=data.get("requires_user_id", False),
+            requires_context=data.get("requires_context", False),
+            tags=data.get("tags", []),
+            author=data.get("author", ""),
+            version=data.get("version", "1.0"),
+        )
+
+
+@dataclass
+class CommandConfig:
+    """Complete configuration for a command.
+
+    Combines metadata from YAML frontmatter with the markdown body
+    that contains the command instructions.
+    """
+
+    name: str
+    description: str
+    body: str  # Markdown content with instructions
+    metadata: CommandMetadata
+    source_file: Path | None = None
+    loaded_at: datetime = field(default_factory=datetime.now)
+
+    @property
+    def aliases(self) -> list[str]:
+        """Get command aliases."""
+        return self.metadata.aliases
+
+    @property
+    def category(self) -> CommandCategory:
+        """Get command category."""
+        return self.metadata.category
+
+    @property
+    def hooks(self) -> dict[str, str]:
+        """Get hook configuration."""
+        return self.metadata.hooks
+
+    def get_all_names(self) -> list[str]:
+        """Get command name and all aliases."""
+        return [self.name] + self.aliases
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "body": self.body,
+            "metadata": self.metadata.to_dict(),
+            "source_file": str(self.source_file) if self.source_file else None,
+            "loaded_at": self.loaded_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CommandConfig:
+        """Create from dictionary."""
+        return cls(
+            name=data["name"],
+            description=data.get("description", ""),
+            body=data.get("body", ""),
+            metadata=CommandMetadata.from_dict(data.get("metadata", {})),
+            source_file=Path(data["source_file"]) if data.get("source_file") else None,
+            loaded_at=datetime.fromisoformat(data["loaded_at"])
+            if "loaded_at" in data
+            else datetime.now(),
+        )
+
+    def format_for_display(self) -> str:
+        """Format command for display in help."""
+        aliases_str = ""
+        if self.aliases:
+            aliases_str = f" (aliases: {', '.join(self.aliases)})"
+
+        return f"/{self.name}{aliases_str} - {self.description}"
+
+    def format_full_help(self) -> str:
+        """Format full help including body."""
+        lines = [
+            f"# /{self.name}",
+            "",
+            self.description,
+            "",
+        ]
+
+        if self.aliases:
+            lines.extend(
+                [
+                    "## Aliases",
+                    ", ".join(f"/{a}" for a in self.aliases),
+                    "",
+                ]
+            )
+
+        if self.metadata.tags:
+            lines.extend(
+                [
+                    "## Tags",
+                    ", ".join(self.metadata.tags),
+                    "",
+                ]
+            )
+
+        lines.extend(
+            [
+                "## Instructions",
+                "",
+                self.body,
+            ]
+        )
+
+        return "\n".join(lines)
+
+
+@dataclass
+class CommandResult:
+    """Result from executing a command."""
+
+    command_name: str
+    success: bool
+    output: str = ""
+    error: str | None = None
+    duration_ms: float = 0.0
+    hooks_fired: list[str] = field(default_factory=list)
+    context_saved: bool = False
+    patterns_applied: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "command_name": self.command_name,
+            "success": self.success,
+            "output": self.output,
+            "error": self.error,
+            "duration_ms": self.duration_ms,
+            "hooks_fired": self.hooks_fired,
+            "context_saved": self.context_saved,
+            "patterns_applied": self.patterns_applied,
+        }

empathy_llm_toolkit/commands/parser.py

@@ -0,0 +1,371 @@
+"""Command Markdown Parser
+
+Parses command markdown files with optional YAML frontmatter.
+
+Architectural patterns inspired by everything-claude-code by Affaan Mustafa.
+See: https://github.com/affaan-m/everything-claude-code (MIT License)
+See: ACKNOWLEDGMENTS.md for full attribution.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from empathy_llm_toolkit.commands.models import CommandCategory, CommandConfig, CommandMetadata
+
+logger = logging.getLogger(__name__)
+
+# YAML frontmatter regex pattern (matches --- at start)
+FRONTMATTER_PATTERN = re.compile(
+    r"^---\s*\n(.*?)\n---\s*\n",
+    re.DOTALL,
+)
+
+# Pattern to extract title from first line (for files without frontmatter)
+TITLE_PATTERN = re.compile(r"^#?\s*(.+?)(?:\s*-\s*(.+))?$")
+
+
+class CommandParser:
+    """Parser for command markdown files.
+
+    Supports two formats:
+    1. With YAML frontmatter (preferred for new commands)
+    2. Plain markdown (legacy format, extracts name from filename/title)
+
+    Example with frontmatter:
+        ---
+        name: compact
+        description: Strategic context compaction
+        category: context
+        aliases: [comp]
+        ---
+
+        ## Overview
+        This command preserves collaboration state...
+
+    Example without frontmatter:
+        Create a git commit with a well-formatted message.
+
+        ## Execution Steps
+        ...
+    """
+
+    # Category inference from command name patterns
+    CATEGORY_PATTERNS: dict[str, CommandCategory] = {
+        r"commit|pr|review-pr": CommandCategory.GIT,
+        r"test|coverage": CommandCategory.TEST,
+        r"docs|manage-docs|explain": CommandCategory.DOCS,
+        r"security|scan": CommandCategory.SECURITY,
+        r"bench|profile|perf": CommandCategory.PERFORMANCE,
+        r"pattern|learn|evaluate": CommandCategory.LEARNING,
+        r"compact|context|memory": CommandCategory.CONTEXT,
+    }
+
+    def __init__(self):
+        """Initialize the parser."""
+        pass
+
+    def parse_file(self, file_path: str | Path) -> CommandConfig:
+        """Parse a command markdown file.
+
+        Args:
+            file_path: Path to the command markdown file
+
+        Returns:
+            CommandConfig instance
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file format is invalid
+
+        """
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"Command file not found: {file_path}")
+
+        with open(file_path, encoding="utf-8") as f:
+            content = f.read()
+
+        return self.parse_content(content, source=file_path)
+
+    def parse_content(
+        self,
+        content: str,
+        source: Path | str | None = None,
+    ) -> CommandConfig:
+        """Parse command markdown content.
+
+        Args:
+            content: Markdown content (optionally with YAML frontmatter)
+            source: Source file path (used for name inference)
+
+        Returns:
+            CommandConfig instance
+
+        """
+        source_path = Path(source) if source else None
+        source_str = str(source) if source else "unknown"
+
+        # Try to extract frontmatter
+        match = FRONTMATTER_PATTERN.match(content)
+
+        if match:
+            # Has frontmatter
+            frontmatter_yaml = match.group(1)
+            body = content[match.end() :].strip()
+            metadata = self._parse_frontmatter(frontmatter_yaml, source_str)
+        else:
+            # No frontmatter - infer from content
+            body = content.strip()
+            metadata = self._infer_metadata(body, source_path)
+
+        # Ensure name is set
+        if not metadata.name:
+            if source_path:
+                metadata.name = source_path.stem
+            else:
+                raise ValueError(f"Cannot determine command name: {source_str}")
+
+        # Extract description from first line if not set
+        if not metadata.description:
+            metadata.description = self._extract_description(body)
+
+        return CommandConfig(
+            name=metadata.name,
+            description=metadata.description,
+            body=body,
+            metadata=metadata,
+            source_file=source_path,
+        )
+
+    def _parse_frontmatter(
+        self,
+        yaml_content: str,
+        source: str,
+    ) -> CommandMetadata:
+        """Parse YAML frontmatter into metadata.
+
+        Args:
+            yaml_content: YAML content from frontmatter
+            source: Source identifier for errors
+
+        Returns:
+            CommandMetadata instance
+
+        """
+        try:
+            import yaml
+
+            data = yaml.safe_load(yaml_content) or {}
+        except ImportError:
+            logger.warning("PyYAML not installed, using basic parsing")
+            data = self._basic_yaml_parse(yaml_content)
+        except Exception as e:
+            raise ValueError(f"Invalid YAML frontmatter in {source}: {e}")
+
+        return CommandMetadata.from_dict(data)
+
+    def _basic_yaml_parse(self, yaml_content: str) -> dict[str, Any]:
+        """Basic YAML parsing without PyYAML (for simple key: value pairs).
+
+        Args:
+            yaml_content: Simple YAML content
+
+        Returns:
+            Parsed dictionary
+
+        """
+        result: dict[str, Any] = {}
+
+        for line in yaml_content.strip().split("\n"):
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+
+            if ":" in line:
+                key, value = line.split(":", 1)
+                key = key.strip()
+                value = value.strip()
+
+                # Handle simple arrays [a, b, c]
+                if value.startswith("[") and value.endswith("]"):
+                    value = [v.strip().strip("'\"") for v in value[1:-1].split(",") if v.strip()]
+                # Handle booleans
+                elif value.lower() in ("true", "yes"):
+                    value = True
+                elif value.lower() in ("false", "no"):
+                    value = False
+                # Handle strings
+                else:
+                    value = value.strip("'\"")
+
+                result[key] = value
+
+        return result
+
+    def _infer_metadata(
+        self,
+        body: str,
+        source_path: Path | None,
+    ) -> CommandMetadata:
+        """Infer metadata from content when no frontmatter present.
+
+        Args:
+            body: Markdown body content
+            source_path: Source file path
+
+        Returns:
+            CommandMetadata with inferred values
+
+        """
+        name = ""
+        description = ""
+
+        # Get name from filename
+        if source_path:
+            name = source_path.stem
+
+        # Try to extract description from first line
+        first_line = body.split("\n")[0].strip() if body else ""
+        if first_line:
+            # Remove markdown heading prefix
+            if first_line.startswith("#"):
+                first_line = first_line.lstrip("#").strip()
+
+            # Check for "title - description" format
+            title_match = TITLE_PATTERN.match(first_line)
+            if title_match:
+                if title_match.group(2):
+                    description = title_match.group(2).strip()
+                else:
+                    description = title_match.group(1).strip()
+
+        # Infer category from name
+        category = self._infer_category(name)
+
+        return CommandMetadata(
+            name=name,
+            description=description,
+            category=category,
+        )
+
+    def _infer_category(self, name: str) -> CommandCategory:
+        """Infer command category from name.
+
+        Args:
+            name: Command name
+
+        Returns:
+            Inferred category
+
+        """
+        name_lower = name.lower()
+
+        for pattern, category in self.CATEGORY_PATTERNS.items():
+            if re.search(pattern, name_lower):
+                return category
+
+        return CommandCategory.UTILITY
+
+    def _extract_description(self, body: str) -> str:
+        """Extract description from body content.
+
+        Args:
+            body: Markdown body
+
+        Returns:
+            Extracted description
+
+        """
+        if not body:
+            return ""
+
+        lines = body.strip().split("\n")
+        first_line = lines[0].strip()
+
+        # Remove markdown heading prefix
+        if first_line.startswith("#"):
+            first_line = first_line.lstrip("#").strip()
+
+        # Check for "title - description" format
+        if " - " in first_line:
+            return first_line.split(" - ", 1)[1].strip()
+
+        # Use first line if it looks like a description
+        if first_line and not first_line.startswith("```"):
+            return first_line[:200]  # Limit length
+
+        return ""
+
+    def validate_file(self, file_path: str | Path) -> list[str]:
+        """Validate a command file without fully parsing.
+
+        Args:
+            file_path: Path to validate
+
+        Returns:
+            List of validation error messages (empty if valid)
+
+        """
+        errors: list[str] = []
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            return [f"File not found: {file_path}"]
+
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                content = f.read()
+        except OSError as e:
+            return [f"Cannot read file: {e}"]
+
+        # Check if file has content
+        if not content.strip():
+            errors.append("File is empty")
+            return errors
+
+        # Check frontmatter if present
+        match = FRONTMATTER_PATTERN.match(content)
+        if match:
+            try:
+                import yaml
+
+                frontmatter = yaml.safe_load(match.group(1)) or {}
+
+                # Validate name if provided
+                name = frontmatter.get("name", "")
+                if name and not re.match(r"^[a-z0-9][-a-z0-9]*$", name):
+                    errors.append(
+                        f"Invalid command name '{name}'. "
+                        "Use lowercase letters, numbers, and hyphens."
+                    )
+
+                # Validate category if provided
+                category = frontmatter.get("category", "")
+                if category:
+                    try:
+                        CommandCategory(category)
+                    except ValueError:
+                        valid = ", ".join(c.value for c in CommandCategory)
+                        errors.append(f"Invalid category '{category}'. Valid: {valid}")
+
+            except ImportError:
+                pass  # Skip YAML validation if not installed
+            except Exception as e:
+                errors.append(f"Invalid YAML frontmatter: {e}")
+
+        # Check body has content
+        body_start = match.end() if match else 0
+        body = content[body_start:].strip()
+
+        if not body:
+            errors.append("Command has no body content")
+
+        return errors