empathy-framework 3.2.3__py3-none-any.whl → 3.8.2__py3-none-any.whl

empathy_os/platform_utils.py

@@ -0,0 +1,261 @@
+"""Cross-Platform Utilities for Empathy Framework
+
+Provides platform-independent utilities for:
+- File paths and directories
+- File encoding
+- Asyncio event loop handling
+- Environment detection
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import asyncio
+import os
+import platform
+from pathlib import Path
+from typing import Any
+
+
+def is_windows() -> bool:
+    """Check if running on Windows."""
+    return platform.system() == "Windows"
+
+
+def is_macos() -> bool:
+    """Check if running on macOS."""
+    return platform.system() == "Darwin"
+
+
+def is_linux() -> bool:
+    """Check if running on Linux."""
+    return platform.system() == "Linux"
+
+
+def get_default_log_dir() -> Path:
+    """Get the default log directory for the current platform.
+
+    Returns:
+        Path: Platform-appropriate log directory
+        - Windows: %APPDATA%/empathy/logs
+        - macOS: ~/Library/Logs/empathy
+        - Linux: /var/log/empathy (if writable) or ~/.local/share/empathy/logs
+
+    """
+    if is_windows():
+        appdata = os.environ.get("APPDATA", os.path.expanduser("~"))
+        return Path(appdata) / "empathy" / "logs"
+    if is_macos():
+        return Path.home() / "Library" / "Logs" / "empathy"
+    # Linux and other Unix
+    var_log = Path("/var/log/empathy")
+    if var_log.exists() or (var_log.parent.exists() and os.access(var_log.parent, os.W_OK)):
+        return var_log
+    # Fallback to user directory
+    return Path.home() / ".local" / "share" / "empathy" / "logs"
+
+
+def get_default_data_dir() -> Path:
+    """Get the default data directory for the current platform.
+
+    Returns:
+        Path: Platform-appropriate data directory
+        - Windows: %APPDATA%/empathy
+        - macOS: ~/Library/Application Support/empathy
+        - Linux: ~/.local/share/empathy
+
+    """
+    if is_windows():
+        appdata = os.environ.get("APPDATA", os.path.expanduser("~"))
+        return Path(appdata) / "empathy"
+    if is_macos():
+        return Path.home() / "Library" / "Application Support" / "empathy"
+    # Linux and other Unix
+    xdg_data = os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))
+    return Path(xdg_data) / "empathy"
+
+
+def get_default_config_dir() -> Path:
+    """Get the default configuration directory for the current platform.
+
+    Returns:
+        Path: Platform-appropriate config directory
+        - Windows: %APPDATA%/empathy
+        - macOS: ~/Library/Preferences/empathy
+        - Linux: ~/.config/empathy
+
+    """
+    if is_windows():
+        appdata = os.environ.get("APPDATA", os.path.expanduser("~"))
+        return Path(appdata) / "empathy"
+    if is_macos():
+        return Path.home() / "Library" / "Preferences" / "empathy"
+    # Linux and other Unix
+    xdg_config = os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))
+    return Path(xdg_config) / "empathy"
+
+
+def get_default_cache_dir() -> Path:
+    """Get the default cache directory for the current platform.
+
+    Returns:
+        Path: Platform-appropriate cache directory
+        - Windows: %LOCALAPPDATA%/empathy/cache
+        - macOS: ~/Library/Caches/empathy
+        - Linux: ~/.cache/empathy
+
+    """
+    if is_windows():
+        localappdata = os.environ.get(
+            "LOCALAPPDATA",
+            os.environ.get("APPDATA", os.path.expanduser("~")),
+        )
+        return Path(localappdata) / "empathy" / "cache"
+    if is_macos():
+        return Path.home() / "Library" / "Caches" / "empathy"
+    # Linux and other Unix
+    xdg_cache = os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache"))
+    return Path(xdg_cache) / "empathy"
+
+
+def setup_asyncio_policy() -> None:
+    """Configure asyncio event loop policy for the current platform.
+
+    On Windows, this uses WindowsSelectorEventLoopPolicy to avoid issues
+    with the default ProactorEventLoop, particularly with subprocesses
+    and certain network operations.
+
+    This should be called early in the application startup, before
+    any asyncio.run() calls.
+    """
+    if is_windows():
+        # Windows requires WindowsSelectorEventLoopPolicy for compatibility
+        # with many libraries and subprocess operations
+        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())  # type: ignore[attr-defined]
+
+
+def safe_run_async(coro: Any, debug: bool = False) -> Any:
+    """Run an async coroutine with platform-appropriate event loop handling.
+
+    This is a cross-platform wrapper for asyncio.run() that handles
+    Windows-specific event loop requirements.
+
+    Args:
+        coro: Coroutine to run
+        debug: Enable asyncio debug mode
+
+    Returns:
+        Result of the coroutine
+
+    """
+    setup_asyncio_policy()
+    return asyncio.run(coro, debug=debug)
+
+
+def open_text_file(path: str | Path, mode: str = "r", **kwargs: Any):
+    """Open a text file with UTF-8 encoding by default.
+
+    This ensures consistent encoding across platforms, as Windows
+    defaults to cp1252 while Unix defaults to UTF-8.
+
+    Args:
+        path: File path to open
+        mode: File mode (r, w, a, etc.)
+        **kwargs: Additional arguments passed to open()
+
+    Returns:
+        File object
+
+    """
+    kwargs.setdefault("encoding", "utf-8")
+    return open(path, mode, **kwargs)
+
+
+def read_text_file(path: str | Path, encoding: str = "utf-8") -> str:
+    """Read a text file with UTF-8 encoding by default.
+
+    Args:
+        path: File path to read
+        encoding: File encoding (default: utf-8)
+
+    Returns:
+        File contents as string
+
+    """
+    return Path(path).read_text(encoding=encoding)
+
+
+def write_text_file(path: str | Path, content: str, encoding: str = "utf-8") -> int:
+    """Write content to a text file with UTF-8 encoding by default.
+
+    Args:
+        path: File path to write
+        content: Content to write
+        encoding: File encoding (default: utf-8)
+
+    Returns:
+        Number of characters written
+
+    """
+    return Path(path).write_text(content, encoding=encoding)
+
+
+def normalize_path(path: str | Path) -> Path:
+    """Normalize a path for the current platform.
+
+    Converts forward slashes to backslashes on Windows and
+    resolves any relative path components.
+
+    Args:
+        path: Path to normalize
+
+    Returns:
+        Normalized Path object
+
+    """
+    return Path(path).resolve()
+
+
+def get_temp_dir() -> Path:
+    """Get the system temporary directory.
+
+    Returns:
+        Path to the system temp directory
+
+    """
+    import tempfile
+
+    return Path(tempfile.gettempdir())
+
+
+def ensure_dir(path: str | Path) -> Path:
+    """Ensure a directory exists, creating it if necessary.
+
+    Args:
+        path: Directory path to ensure
+
+    Returns:
+        Path object for the directory
+
+    """
+    dir_path = Path(path)
+    dir_path.mkdir(parents=True, exist_ok=True)
+    return dir_path
+
+
+# Platform information for diagnostics
+PLATFORM_INFO = {
+    "system": platform.system(),
+    "release": platform.release(),
+    "version": platform.version(),
+    "machine": platform.machine(),
+    "python_version": platform.python_version(),
+    "is_windows": is_windows(),
+    "is_macos": is_macos(),
+    "is_linux": is_linux(),
+}
+
+
+def get_platform_info() -> dict:
+    """Get platform information for diagnostics."""
+    return PLATFORM_INFO.copy()

empathy_os/plugins/__init__.py

@@ -0,0 +1,28 @@
+"""Empathy Framework - Plugin System
+
+Enables modular extension of the Empathy Framework with domain-specific plugins.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from .base import (
+                   BasePlugin,
+                   BaseWizard,
+                   PluginError,
+                   PluginLoadError,
+                   PluginMetadata,
+                   PluginValidationError,
+)
+from .registry import PluginRegistry, get_global_registry
+
+__all__ = [
+    "BasePlugin",
+    "BaseWizard",
+    "PluginError",
+    "PluginLoadError",
+    "PluginMetadata",
+    "PluginRegistry",
+    "PluginValidationError",
+    "get_global_registry",
+]

empathy_os/plugins/base.py

@@ -0,0 +1,361 @@
+"""Empathy Framework - Plugin System Base Classes
+
+This module provides the core abstractions for creating domain-specific plugins
+that extend the Empathy Framework.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PluginMetadata:
+    """Metadata about a plugin"""
+
+    name: str
+    version: str
+    domain: str
+    description: str
+    author: str
+    license: str
+    requires_core_version: str  # Minimum core framework version
+    dependencies: list[str] | None = None  # Additional package dependencies
+
+
+class BaseWizard(ABC):
+    """Universal base class for all wizards across all domains.
+
+    This replaces domain-specific base classes (BaseCoachWizard, etc.)
+    to provide a unified interface.
+
+    Design Philosophy:
+    - Domain-agnostic: Works for software, healthcare, finance, etc.
+    - Level-aware: Each wizard declares its empathy level
+    - Pattern-contributing: Wizards share learnings via pattern library
+    """
+
+    def __init__(self, name: str, domain: str, empathy_level: int, category: str | None = None):
+        """Initialize a wizard
+
+        Args:
+            name: Human-readable wizard name
+            domain: Domain this wizard belongs to (e.g., 'software', 'healthcare')
+            empathy_level: Which empathy level this wizard operates at (1-5)
+            category: Optional category within domain
+
+        """
+        self.name = name
+        self.domain = domain
+        self.empathy_level = empathy_level
+        self.category = category
+        self.logger = logging.getLogger(f"wizard.{domain}.{name}")
+
+    @abstractmethod
+    async def analyze(self, context: dict[str, Any]) -> dict[str, Any]:
+        """Analyze the given context and return results.
+
+        This is the main entry point for all wizards. The context structure
+        is domain-specific but the return format should follow a standard pattern.
+        Subclasses must implement domain-specific analysis logic that aligns with
+        the wizard's empathy level.
+
+        Args:
+            context: dict[str, Any]
+                Domain-specific context dictionary. Must contain all fields returned
+                by get_required_context(). Examples:
+                - Software: {'code': str, 'file_path': str, 'language': str}
+                - Healthcare: {'patient_id': str, 'vitals': dict, 'medications': list}
+                - Finance: {'transactions': list, 'account': dict, 'period': str}
+
+        Returns:
+            dict[str, Any]
+                Analysis results dictionary containing:
+                - 'issues': list[dict] - Current issues found (Levels 1-3 analysis)
+                - 'predictions': list[dict] - Future issues predicted (Level 4 analysis)
+                - 'recommendations': list[dict] - Actionable next steps
+                - 'patterns': list[str] - Patterns detected for the pattern library
+                - 'confidence': float - Confidence score between 0.0 and 1.0
+                - 'wizard': str - Name of the wizard that performed analysis
+                - 'empathy_level': int - Empathy level of this analysis (1-5)
+                - 'timestamp': str - ISO format timestamp of analysis
+
+        Raises:
+            ValueError: If context is invalid or missing required fields
+            RuntimeError: If analysis fails due to domain-specific errors
+            TimeoutError: If analysis takes too long to complete
+
+        Note:
+            - Validate context using self.validate_context() at the beginning
+            - Each issue/prediction should include 'severity', 'description', 'affected_component'
+            - Use self.contribute_patterns() to extract learnings for the pattern library
+            - Confidence scores should reflect uncertainty in the analysis
+            - This method is async to support long-running analyses
+
+        """
+
+    @abstractmethod
+    def get_required_context(self) -> list[str]:
+        """Declare what context fields this wizard needs.
+
+        This method defines the contract between the caller and the wizard.
+        The caller must provide all declared fields before calling analyze().
+        This enables validation via validate_context() and helps with introspection.
+
+        Returns:
+            list[str]
+                List of required context field names (keys). Each string should be
+                a simple identifier that matches the keys in context dictionaries
+                passed to analyze().
+
+        Examples:
+            Software wizard returns: ['code', 'file_path', 'language']
+            Healthcare wizard returns: ['patient_id', 'vitals', 'medications']
+            Finance wizard returns: ['transactions', 'account_id', 'period']
+
+        Note:
+            - Must return at least one field (even if minimal)
+            - Field names should match exactly what analyze() expects in context
+            - Order is not significant but consistency helps with documentation
+            - Consider validation requirements when declaring fields
+            - Used by validate_context() to check required fields before analyze()
+
+        """
+
+    def validate_context(self, context: dict[str, Any]) -> bool:
+        """Validate that context contains required fields.
+
+        Args:
+            context: Context to validate
+
+        Returns:
+            True if valid, raises ValueError if invalid
+
+        """
+        required = self.get_required_context()
+        missing = [key for key in required if key not in context]
+
+        if missing:
+            raise ValueError(f"Wizard '{self.name}' missing required context: {missing}")
+
+        return True
+
+    def get_empathy_level(self) -> int:
+        """Get the empathy level this wizard operates at"""
+        return self.empathy_level
+
+    def contribute_patterns(self, analysis_result: dict[str, Any]) -> dict[str, Any]:
+        """Extract patterns from analysis for the shared pattern library.
+
+        This enables cross-domain learning (Level 5 Systems Empathy).
+
+        Args:
+            analysis_result: Result from analyze()
+
+        Returns:
+            Dictionary of patterns in standard format
+
+        """
+        # Default implementation - override for custom pattern extraction
+        return {
+            "wizard": self.name,
+            "domain": self.domain,
+            "timestamp": datetime.now().isoformat(),
+            "patterns": analysis_result.get("patterns", []),
+        }
+
+
+class BasePlugin(ABC):
+    """Base class for domain plugins.
+
+    A plugin is a collection of wizards and patterns for a specific domain.
+
+    Example:
+        - SoftwarePlugin: 16+ coach wizards for code analysis
+        - HealthcarePlugin: Clinical and compliance wizards
+        - FinancePlugin: Fraud detection, compliance wizards
+
+    """
+
+    def __init__(self):
+        self.logger = logging.getLogger(f"plugin.{self.get_metadata().domain}")
+        self._wizards: dict[str, type[BaseWizard]] = {}
+        self._initialized = False
+
+    @abstractmethod
+    def get_metadata(self) -> PluginMetadata:
+        """Return metadata about this plugin.
+
+        This method provides essential information about the plugin that the
+        framework uses for loading, validation, and discovery. It must return
+        consistent metadata across multiple calls.
+
+        Returns:
+            PluginMetadata
+                A PluginMetadata instance containing:
+                - name: str - Human-readable plugin name (e.g., 'Software Plugin')
+                - version: str - Semantic version string (e.g., '1.0.0')
+                - domain: str - Domain this plugin serves (e.g., 'software', 'healthcare')
+                - description: str - Brief description of plugin functionality
+                - author: str - Plugin author or organization name
+                - license: str - License identifier (e.g., 'Apache-2.0', 'MIT')
+                - requires_core_version: str - Minimum core framework version (e.g., '1.0.0')
+                - dependencies: list[str] - Optional list of required packages
+
+        Note:
+            - Called during plugin initialization to validate compatibility
+            - Used for plugin discovery and listing
+            - Should be immutable (return same values each call)
+            - Version should follow semantic versioning
+            - Domain names should be lowercase and consistent across plugins
+            - Core version requirement ensures framework compatibility
+
+        """
+
+    @abstractmethod
+    def register_wizards(self) -> dict[str, type[BaseWizard]]:
+        """Register all wizards provided by this plugin.
+
+        This method defines all analysis wizards available in this plugin.
+        Wizards are lazy-instantiated by get_wizard() when first requested.
+        This method is called during plugin initialization.
+
+        Returns:
+            dict[str, type[BaseWizard]]
+                Dictionary mapping wizard identifiers to Wizard classes (not instances).
+                Keys should be lowercase, snake_case identifiers. Values should be
+                uninstantiated class references.
+
+        Returns:
+            dict[str, type[BaseWizard]]
+                Mapping structure:
+                {
+                    'wizard_id': WizardClass,
+                    'another_wizard': AnotherWizardClass,
+                    ...
+                }
+
+        Example:
+            Software plugin might return:
+            {
+                'security': SecurityWizard,
+                'performance': PerformanceWizard,
+                'maintainability': MaintainabilityWizard,
+                'accessibility': AccessibilityWizard,
+            }
+
+        Note:
+            - Return only the class, not instances (instantiation is lazy)
+            - Use consistent, descriptive wizard IDs
+            - All returned classes must be subclasses of BaseWizard
+            - Can return empty dict {} if plugin provides no wizards initially
+            - Called once during initialization via initialize()
+            - Framework caches results in self._wizards
+
+        """
+
+    def register_patterns(self) -> dict[str, Any]:
+        """Register domain-specific patterns for the pattern library.
+
+        Returns:
+            Dictionary of patterns in standard format
+
+        """
+        # Optional - override if plugin provides pre-built patterns
+        return {}
+
+    def initialize(self) -> None:
+        """Initialize the plugin (lazy initialization).
+
+        Called once before first use. Override to perform setup:
+        - Load configuration
+        - Initialize domain-specific services
+        - Validate dependencies
+        """
+        if self._initialized:
+            return
+
+        self.logger.info(f"Initializing plugin: {self.get_metadata().name}")
+
+        # Register wizards
+        self._wizards = self.register_wizards()
+
+        self.logger.info(
+            f"Plugin '{self.get_metadata().name}' initialized with {len(self._wizards)} wizards",
+        )
+
+        self._initialized = True
+
+    def get_wizard(self, wizard_id: str) -> type[BaseWizard] | None:
+        """Get a wizard by ID.
+
+        Args:
+            wizard_id: Wizard identifier
+
+        Returns:
+            Wizard class or None if not found
+
+        """
+        if not self._initialized:
+            self.initialize()
+
+        return self._wizards.get(wizard_id)
+
+    def list_wizards(self) -> list[str]:
+        """List all wizard IDs provided by this plugin.
+
+        Returns:
+            List of wizard identifiers
+
+        """
+        if not self._initialized:
+            self.initialize()
+
+        return list(self._wizards.keys())
+
+    def get_wizard_info(self, wizard_id: str) -> dict[str, Any] | None:
+        """Get information about a wizard without instantiating it.
+
+        Args:
+            wizard_id: Wizard identifier
+
+        Returns:
+            Dictionary with wizard metadata
+
+        """
+        wizard_class = self.get_wizard(wizard_id)
+        if not wizard_class:
+            return None
+
+        # Create temporary instance to get metadata
+        # (wizards should be lightweight to construct)
+        # Subclasses provide their own defaults for name, domain, empathy_level
+        temp_instance = wizard_class()  # type: ignore[call-arg]
+
+        return {
+            "id": wizard_id,
+            "name": temp_instance.name,
+            "domain": temp_instance.domain,
+            "empathy_level": temp_instance.empathy_level,
+            "category": temp_instance.category,
+            "required_context": temp_instance.get_required_context(),
+        }
+
+
+class PluginError(Exception):
+    """Base exception for plugin-related errors"""
+
+
+class PluginLoadError(PluginError):
+    """Raised when plugin fails to load"""
+
+
+class PluginValidationError(PluginError):
+    """Raised when plugin fails validation"""