attune-ai 2.0.0__py3-none-any.whl

attune_llm/agent_factory/resilient.py

@@ -0,0 +1,320 @@
+"""Resilient Agent Wrapper
+
+Applies production-ready resilience patterns (circuit breaker, retry, timeout,
+fallback) to any agent created by the Agent Factory.
+
+Usage:
+    from attune_llm.agent_factory import AgentFactory
+    from attune_llm.agent_factory.resilient import ResilientAgent, ResilienceConfig
+
+    factory = AgentFactory()
+    agent = factory.create_agent(name="researcher", role="researcher")
+
+    # Wrap with resilience
+    resilient_agent = ResilientAgent(agent, ResilienceConfig(
+        enable_circuit_breaker=True,
+        failure_threshold=3,
+        enable_retry=True,
+        max_attempts=3
+    ))
+
+    result = await resilient_agent.invoke("Research AI trends")
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import asyncio
+import functools
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from attune_llm.agent_factory.base import AgentConfig, BaseAgent
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ResilienceConfig:
+    """Configuration for resilience patterns."""
+
+    # Circuit Breaker
+    enable_circuit_breaker: bool = True
+    failure_threshold: int = 3
+    reset_timeout: float = 60.0
+    half_open_max_calls: int = 3
+
+    # Retry
+    enable_retry: bool = True
+    max_attempts: int = 2
+    initial_delay: float = 1.0
+    backoff_factor: float = 2.0
+    max_delay: float = 30.0
+    jitter: bool = True
+
+    # Timeout
+    enable_timeout: bool = True
+    timeout_seconds: float = 30.0
+
+    # Fallback
+    enable_fallback: bool = False
+    fallback_value: Any = field(
+        default_factory=lambda: {
+            "output": "Service temporarily unavailable",
+            "metadata": {"fallback": True},
+        },
+    )
+
+    @classmethod
+    def from_agent_config(cls, config: AgentConfig) -> "ResilienceConfig":
+        """Create ResilienceConfig from AgentConfig resilience fields."""
+        return cls(
+            enable_circuit_breaker=getattr(config, "resilience_enabled", False),
+            failure_threshold=getattr(config, "circuit_breaker_threshold", 3),
+            enable_retry=getattr(config, "resilience_enabled", False),
+            max_attempts=getattr(config, "retry_max_attempts", 2),
+            enable_timeout=getattr(config, "resilience_enabled", False),
+            timeout_seconds=getattr(config, "timeout_seconds", 30.0),
+        )
+
+
+class ResilientAgent(BaseAgent):
+    """Agent wrapper that applies resilience patterns.
+
+    Wraps any BaseAgent implementation with:
+    - Circuit breaker: Prevents cascading failures
+    - Retry with backoff: Handles transient errors
+    - Timeout: Prevents hanging operations
+    - Fallback: Graceful degradation
+
+    The wrapper preserves the underlying agent's interface while adding
+    fault tolerance capabilities.
+    """
+
+    def __init__(self, agent: BaseAgent, config: ResilienceConfig | None = None):
+        """Initialize resilient agent wrapper.
+
+        Args:
+            agent: The underlying agent to wrap
+            config: Resilience configuration (uses defaults if not provided)
+
+        """
+        # Initialize with wrapped agent's config
+        super().__init__(agent.config)
+        self._wrapped = agent
+        self._resilience_config = config or ResilienceConfig()
+        self._circuit_breaker: Any = None
+        self._setup_resilience()
+
+    def _setup_resilience(self) -> None:
+        """Set up resilience decorators based on config."""
+        config = self._resilience_config
+
+        # Set up circuit breaker if enabled
+        if config.enable_circuit_breaker:
+            try:
+                from attune.resilience import CircuitBreaker
+
+                self._circuit_breaker = CircuitBreaker(
+                    name=f"agent_{self.name}",
+                    failure_threshold=config.failure_threshold,
+                    reset_timeout=config.reset_timeout,
+                    half_open_max_calls=config.half_open_max_calls,
+                )
+            except ImportError:
+                logger.warning("attune.resilience not available, circuit breaker disabled")
+
+    async def invoke(self, input_data: str | dict, context: dict | None = None) -> dict:
+        """Invoke the agent with resilience patterns applied.
+
+        Args:
+            input_data: User input or structured data
+            context: Optional context (previous results, shared state)
+
+        Returns:
+            Dict with at least {"output": str, "metadata": dict}
+
+        Raises:
+            CircuitOpenError: If circuit breaker is open
+            asyncio.TimeoutError: If operation times out and no fallback
+            Exception: If all retries exhausted and no fallback
+
+        """
+        config = self._resilience_config
+
+        # Build the resilient call chain
+        async def _call():
+            return await self._wrapped.invoke(input_data, context)
+
+        # Apply timeout
+        if config.enable_timeout:
+            _call = self._with_timeout(_call, config.timeout_seconds)
+
+        # Apply retry
+        if config.enable_retry:
+            _call = self._with_retry(
+                _call,
+                config.max_attempts,
+                config.initial_delay,
+                config.backoff_factor,
+                config.max_delay,
+                config.jitter,
+            )
+
+        # Apply circuit breaker
+        if config.enable_circuit_breaker and self._circuit_breaker:
+            _call = self._with_circuit_breaker(_call)
+
+        # Execute with optional fallback
+        try:
+            result = await _call()
+            # Add resilience metadata
+            if "metadata" in result:
+                result["metadata"]["resilience"] = {
+                    "circuit_breaker_enabled": config.enable_circuit_breaker,
+                    "retry_enabled": config.enable_retry,
+                    "timeout_enabled": config.enable_timeout,
+                }
+            return dict(result)
+        except Exception as e:
+            if config.enable_fallback:
+                logger.warning(f"Agent {self.name} failed, using fallback: {e}")
+                fallback = config.fallback_value
+                if callable(fallback):
+                    return dict(fallback(input_data, context, e))
+                return dict(fallback) if isinstance(fallback, dict) else {"output": fallback}
+            raise
+
+    async def stream(self, input_data: str | dict, context: dict | None = None):
+        """Stream agent response with resilience patterns.
+
+        Note: Streaming has limited resilience support (timeout only).
+        Circuit breaker and retry work at the full response level.
+        """
+        config = self._resilience_config
+
+        async def _stream():
+            async for chunk in self._wrapped.stream(input_data, context):
+                yield chunk
+
+        # Apply timeout to entire stream
+        if config.enable_timeout:
+            try:
+                async with asyncio.timeout(config.timeout_seconds):  # type: ignore[attr-defined]
+                    async for chunk in _stream():
+                        yield chunk
+            except asyncio.TimeoutError:
+                if config.enable_fallback:
+                    yield {"output": "Stream timed out", "metadata": {"fallback": True}}
+                else:
+                    raise
+        else:
+            async for chunk in _stream():
+                yield chunk
+
+    def _with_timeout(self, func, timeout_seconds: float):
+        """Wrap function with timeout."""
+
+        @functools.wraps(func)
+        async def wrapper():
+            return await asyncio.wait_for(func(), timeout=timeout_seconds)
+
+        return wrapper
+
+    def _with_retry(
+        self,
+        func,
+        max_attempts: int,
+        initial_delay: float,
+        backoff_factor: float,
+        max_delay: float,
+        jitter: bool,
+    ):
+        """Wrap function with retry logic."""
+        import random
+
+        @functools.wraps(func)
+        async def wrapper():
+            last_exception = None
+            delay = initial_delay
+
+            for attempt in range(max_attempts):
+                try:
+                    return await func()
+                except asyncio.TimeoutError:
+                    # Don't retry timeouts by default
+                    raise
+                except Exception as e:
+                    last_exception = e
+                    if attempt < max_attempts - 1:
+                        actual_delay = delay
+                        if jitter:
+                            actual_delay = delay * (0.5 + random.random())
+                        actual_delay = min(actual_delay, max_delay)
+                        logger.debug(
+                            f"Agent {self.name} attempt {attempt + 1} failed, "
+                            f"retrying in {actual_delay:.2f}s: {e}",
+                        )
+                        await asyncio.sleep(actual_delay)
+                        delay = min(delay * backoff_factor, max_delay)
+
+            raise last_exception
+
+        return wrapper
+
+    def _with_circuit_breaker(self, func):
+        """Wrap function with circuit breaker."""
+
+        @functools.wraps(func)
+        async def wrapper():
+            from attune.resilience import CircuitOpenError
+
+            # Check if circuit is open (failing fast)
+            if self._circuit_breaker.is_open:
+                reset_time = self._circuit_breaker.get_time_until_reset()
+                raise CircuitOpenError(
+                    name=f"agent_{self.name}",
+                    reset_time=reset_time,
+                )
+
+            try:
+                result = await func()
+                self._circuit_breaker.record_success()
+                return result
+            except Exception as e:
+                self._circuit_breaker.record_failure(e)
+                raise
+
+        return wrapper
+
+    # Delegate other methods to wrapped agent
+    def add_tool(self, tool: Any) -> None:
+        """Add a tool to the wrapped agent."""
+        self._wrapped.add_tool(tool)
+
+    def get_conversation_history(self) -> list[dict]:
+        """Get conversation history from wrapped agent."""
+        return self._wrapped.get_conversation_history()
+
+    def clear_history(self) -> None:
+        """Clear conversation history in wrapped agent."""
+        self._wrapped.clear_history()
+
+    @property
+    def model(self) -> str:
+        """Get the model being used by wrapped agent."""
+        return self._wrapped.model
+
+    @property
+    def circuit_state(self) -> str | None:
+        """Get current circuit breaker state."""
+        if self._circuit_breaker:
+            return str(self._circuit_breaker.state.value)
+        return None
+
+    def reset_circuit_breaker(self) -> None:
+        """Manually reset the circuit breaker."""
+        if self._circuit_breaker:
+            self._circuit_breaker.reset()
+            logger.info(f"Circuit breaker reset for agent {self.name}")

attune_llm/agents_md/__init__.py

@@ -0,0 +1,22 @@
+"""Markdown Agent System
+
+Define agents in Markdown files with YAML frontmatter for portability.
+Integrates with Empathy Framework's UnifiedAgentConfig and model tier system.
+
+Markdown agent format 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
+Licensed under Fair Source License 0.9
+"""
+
+from attune_llm.agents_md.loader import AgentLoader
+from attune_llm.agents_md.parser import MarkdownAgentParser
+from attune_llm.agents_md.registry import AgentRegistry
+
+__all__ = [
+    "MarkdownAgentParser",
+    "AgentLoader",
+    "AgentRegistry",
+]

attune_llm/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 attune_llm.agents_md.parser import MarkdownAgentParser
+from attune_llm.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