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

empathy_llm_toolkit/agents_md/loader.py

@@ -0,0 +1,218 @@
+"""Agent Loader
+
+Loads agents from directory structures.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import logging
+from collections.abc import Iterator
+from pathlib import Path
+
+from empathy_llm_toolkit.agents_md.parser import MarkdownAgentParser
+from empathy_llm_toolkit.config.unified import UnifiedAgentConfig
+
+logger = logging.getLogger(__name__)
+
+
+class AgentLoader:
+    """Loader for discovering and loading markdown agent files.
+
+    Scans directories for .md files with agent definitions and loads them
+    into UnifiedAgentConfig instances.
+
+    Example:
+        loader = AgentLoader()
+
+        # Load a single agent
+        config = loader.load("agents/architect.md")
+
+        # Load all agents from a directory
+        agents = loader.load_directory("agents/")
+
+        # Discover and iterate agents lazily
+        for config in loader.discover("agents/"):
+            print(config.name)
+    """
+
+    def __init__(self, parser: MarkdownAgentParser | None = None):
+        """Initialize the loader.
+
+        Args:
+            parser: Optional custom parser instance
+
+        """
+        self.parser = parser or MarkdownAgentParser()
+
+    def load(self, file_path: str | Path) -> UnifiedAgentConfig:
+        """Load a single agent file.
+
+        Args:
+            file_path: Path to the agent markdown file
+
+        Returns:
+            UnifiedAgentConfig instance
+
+        """
+        return self.parser.parse_file(file_path)
+
+    def load_directory(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> dict[str, UnifiedAgentConfig]:
+        """Load all agents from a directory.
+
+        Args:
+            directory: Directory to scan for .md files
+            recursive: If True, scan subdirectories
+
+        Returns:
+            Dictionary mapping agent names to configs
+
+        """
+        agents = {}
+
+        for config in self.discover(directory, recursive=recursive):
+            if config.name in agents:
+                logger.warning(
+                    "Duplicate agent name '%s' - keeping first occurrence",
+                    config.name,
+                )
+                continue
+            agents[config.name] = config
+
+        logger.info("Loaded %d agent(s) from %s", len(agents), directory)
+        return agents
+
+    def discover(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> Iterator[UnifiedAgentConfig]:
+        """Discover and yield agents from a directory.
+
+        Args:
+            directory: Directory to scan
+            recursive: If True, scan subdirectories
+
+        Yields:
+            UnifiedAgentConfig instances
+
+        """
+        directory = Path(directory)
+
+        if not directory.exists():
+            logger.warning("Agent directory not found: %s", directory)
+            return
+
+        if not directory.is_dir():
+            raise ValueError(f"Not a directory: {directory}")
+
+        # Get pattern for globbing
+        pattern = "**/*.md" if recursive else "*.md"
+
+        for file_path in sorted(directory.glob(pattern)):
+            if not file_path.is_file():
+                continue
+
+            # Skip files that don't look like agent definitions
+            if file_path.name.startswith("_"):
+                continue
+            if file_path.name.upper() in ("README.MD", "CHANGELOG.MD"):
+                continue
+
+            try:
+                config = self.parser.parse_file(file_path)
+                yield config
+            except ValueError as e:
+                logger.warning("Skipping invalid agent file %s: %s", file_path, e)
+            except Exception as e:
+                logger.error("Error loading agent file %s: %s", file_path, e)
+
+    def validate_directory(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> dict[str, list[str]]:
+        """Validate all agent files in a directory.
+
+        Args:
+            directory: Directory to validate
+            recursive: If True, scan subdirectories
+
+        Returns:
+            Dictionary mapping file paths to lists of errors
+
+        """
+        directory = Path(directory)
+        results = {}
+
+        pattern = "**/*.md" if recursive else "*.md"
+
+        for file_path in sorted(directory.glob(pattern)):
+            if not file_path.is_file():
+                continue
+            if file_path.name.startswith("_"):
+                continue
+            if file_path.name.upper() in ("README.MD", "CHANGELOG.MD"):
+                continue
+
+            errors = self.parser.validate_file(file_path)
+            if errors:
+                results[str(file_path)] = errors
+
+        return results
+
+    def get_agent_names(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> list[str]:
+        """Get list of agent names in a directory without fully loading.
+
+        Args:
+            directory: Directory to scan
+            recursive: If True, scan subdirectories
+
+        Returns:
+            List of agent names
+
+        """
+        names = []
+        for config in self.discover(directory, recursive=recursive):
+            names.append(config.name)
+        return names
+
+
+def load_agents_from_paths(
+    paths: list[str | Path],
+    parser: MarkdownAgentParser | None = None,
+) -> dict[str, UnifiedAgentConfig]:
+    """Load agents from multiple paths (files or directories).
+
+    Args:
+        paths: List of file or directory paths
+        parser: Optional custom parser
+
+    Returns:
+        Dictionary mapping agent names to configs
+
+    """
+    loader = AgentLoader(parser=parser)
+    agents = {}
+
+    for path in paths:
+        path = Path(path)
+
+        if path.is_file():
+            config = loader.load(path)
+            agents[config.name] = config
+        elif path.is_dir():
+            dir_agents = loader.load_directory(path)
+            agents.update(dir_agents)
+        else:
+            logger.warning("Path not found: %s", path)
+
+    return agents

empathy_llm_toolkit/agents_md/parser.py

@@ -0,0 +1,271 @@
+"""Markdown Agent Parser
+
+Parses Markdown files with YAML frontmatter into UnifiedAgentConfig.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from empathy_llm_toolkit.config.unified import ModelTier, Provider, UnifiedAgentConfig
+
+logger = logging.getLogger(__name__)
+
+# YAML frontmatter regex pattern
+FRONTMATTER_PATTERN = re.compile(
+    r"^---\s*\n(.*?)\n---\s*\n",
+    re.DOTALL,
+)
+
+
+class MarkdownAgentParser:
+    """Parser for Markdown agent definition files.
+
+    Parses files with YAML frontmatter containing agent configuration,
+    followed by Markdown content that becomes the system prompt.
+
+    Example file format:
+        ---
+        name: architect
+        description: Software architecture specialist
+        model: capable
+        tools: Read, Grep, Glob
+        empathy_level: 4
+        ---
+
+        You are an expert software architect...
+
+    Example usage:
+        parser = MarkdownAgentParser()
+        config = parser.parse_file("agents/architect.md")
+    """
+
+    # Mapping from string model names to ModelTier
+    MODEL_TIER_MAP = {
+        "cheap": ModelTier.CHEAP,
+        "haiku": ModelTier.CHEAP,
+        "capable": ModelTier.CAPABLE,
+        "sonnet": ModelTier.CAPABLE,
+        "premium": ModelTier.PREMIUM,
+        "opus": ModelTier.PREMIUM,
+    }
+
+    # Mapping from string provider names to Provider
+    PROVIDER_MAP = {
+        "anthropic": Provider.ANTHROPIC,
+        "openai": Provider.OPENAI,
+        "local": Provider.LOCAL,
+    }
+
+    def __init__(self):
+        """Initialize the parser."""
+        pass
+
+    def parse_file(self, file_path: str | Path) -> UnifiedAgentConfig:
+        """Parse a Markdown agent file into UnifiedAgentConfig.
+
+        Args:
+            file_path: Path to the Markdown agent file
+
+        Returns:
+            UnifiedAgentConfig 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"Agent file not found: {file_path}")
+
+        with open(file_path, encoding="utf-8") as f:
+            content = f.read()
+
+        return self.parse_content(content, source=str(file_path))
+
+    def parse_content(
+        self,
+        content: str,
+        source: str = "unknown",
+    ) -> UnifiedAgentConfig:
+        """Parse Markdown content into UnifiedAgentConfig.
+
+        Args:
+            content: Markdown content with YAML frontmatter
+            source: Source identifier for error messages
+
+        Returns:
+            UnifiedAgentConfig instance
+
+        Raises:
+            ValueError: If content format is invalid
+
+        """
+        # Extract frontmatter
+        match = FRONTMATTER_PATTERN.match(content)
+
+        if not match:
+            raise ValueError(f"Invalid agent file format - missing YAML frontmatter: {source}")
+
+        frontmatter_yaml = match.group(1)
+        body = content[match.end() :].strip()
+
+        # Parse YAML
+        try:
+            import yaml
+
+            frontmatter = yaml.safe_load(frontmatter_yaml) or {}
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML frontmatter in {source}: {e}")
+
+        return self._create_config(frontmatter, body, source)
+
+    def _create_config(
+        self,
+        frontmatter: dict[str, Any],
+        body: str,
+        source: str,
+    ) -> UnifiedAgentConfig:
+        """Create UnifiedAgentConfig from parsed data.
+
+        Args:
+            frontmatter: Parsed YAML frontmatter
+            body: Markdown body content
+            source: Source identifier
+
+        Returns:
+            UnifiedAgentConfig instance
+
+        """
+        # Required field
+        name = frontmatter.get("name")
+        if not name:
+            raise ValueError(f"Agent file missing required 'name' field: {source}")
+
+        # Parse model tier
+        model_str = frontmatter.get("model", "capable").lower()
+        model_tier = self.MODEL_TIER_MAP.get(model_str, ModelTier.CAPABLE)
+
+        # Parse provider
+        provider_str = frontmatter.get("provider", "anthropic").lower()
+        provider = self.PROVIDER_MAP.get(provider_str, Provider.ANTHROPIC)
+
+        # Parse tools list
+        tools_raw = frontmatter.get("tools", [])
+        if isinstance(tools_raw, str):
+            # Handle comma-separated string
+            tools = [t.strip() for t in tools_raw.split(",")]
+        else:
+            tools = list(tools_raw)
+
+        # Parse capabilities
+        capabilities = frontmatter.get("capabilities", [])
+        if isinstance(capabilities, str):
+            capabilities = [c.strip() for c in capabilities.split(",")]
+
+        # Build config
+        config = UnifiedAgentConfig(
+            name=name,
+            role=frontmatter.get("role", name),
+            description=frontmatter.get("description", ""),
+            model_tier=model_tier,
+            model_override=frontmatter.get("model_override"),
+            provider=provider,
+            empathy_level=int(frontmatter.get("empathy_level", 4)),
+            memory_enabled=frontmatter.get("memory_enabled", True),
+            pattern_learning=frontmatter.get("pattern_learning", True),
+            cost_tracking=frontmatter.get("cost_tracking", True),
+            use_patterns=frontmatter.get("use_patterns", True),
+            temperature=float(frontmatter.get("temperature", 0.7)),
+            max_tokens=int(frontmatter.get("max_tokens", 4096)),
+            timeout=int(frontmatter.get("timeout", 120)),
+            retry_attempts=int(frontmatter.get("retry_attempts", 3)),
+            retry_delay=float(frontmatter.get("retry_delay", 1.0)),
+            system_prompt=body if body else None,
+            tools=tools,
+            capabilities=capabilities,
+            framework_options=frontmatter.get("framework_options", {}),
+            extra={
+                "source_file": source,
+                "raw_frontmatter": frontmatter,
+                "interaction_mode": frontmatter.get("interaction_mode", "standard"),
+                "socratic_config": frontmatter.get("socratic_config", {}),
+            },
+        )
+
+        logger.debug("Parsed agent config: %s from %s", name, source)
+        return config
+
+    def validate_file(self, file_path: str | Path) -> list[str]:
+        """Validate a Markdown agent file without fully parsing.
+
+        Args:
+            file_path: Path to validate
+
+        Returns:
+            List of validation error messages (empty if valid)
+
+        """
+        errors = []
+        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 frontmatter
+        match = FRONTMATTER_PATTERN.match(content)
+        if not match:
+            errors.append("Missing YAML frontmatter (must start with ---)")
+            return errors
+
+        # Parse YAML
+        try:
+            import yaml
+
+            frontmatter = yaml.safe_load(match.group(1)) or {}
+        except yaml.YAMLError as e:
+            errors.append(f"Invalid YAML: {e}")
+            return errors
+
+        # Check required fields
+        if not frontmatter.get("name"):
+            errors.append("Missing required field: name")
+
+        # Validate model tier
+        model = frontmatter.get("model", "").lower()
+        if model and model not in self.MODEL_TIER_MAP:
+            errors.append(
+                f"Invalid model '{model}'. Valid options: {', '.join(self.MODEL_TIER_MAP.keys())}"
+            )
+
+        # Validate provider
+        provider = frontmatter.get("provider", "").lower()
+        if provider and provider not in self.PROVIDER_MAP:
+            errors.append(
+                f"Invalid provider '{provider}'. "
+                f"Valid options: {', '.join(self.PROVIDER_MAP.keys())}"
+            )
+
+        # Validate empathy level
+        empathy_level = frontmatter.get("empathy_level")
+        if empathy_level is not None:
+            try:
+                level = int(empathy_level)
+                if not 1 <= level <= 5:
+                    errors.append(f"empathy_level must be 1-5, got {level}")
+            except (TypeError, ValueError):
+                errors.append(f"empathy_level must be an integer, got {empathy_level}")
+
+        return errors