empathy-framework 5.3.0__py3-none-any.whl → 5.4.0__py3-none-any.whl

empathy_os/cache_stats.py

@@ -1,298 +0,0 @@
-"""Cache Statistics and Performance Reporting
-
-Provides comprehensive reporting on cache performance metrics and recommendations.
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-from dataclasses import dataclass
-from typing import Any
-
-from empathy_os.cache_monitor import CacheMonitor, CacheStats
-
-
-@dataclass
-class CacheHealthScore:
-    """Health assessment for a cache."""
-
-    cache_name: str
-    hit_rate: float
-    health: str  # "excellent", "good", "fair", "poor"
-    confidence: str  # "high", "medium", "low"
-    recommendation: str
-    reasons: list[str]
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary."""
-        return {
-            "cache_name": self.cache_name,
-            "hit_rate": round(self.hit_rate, 4),
-            "health": self.health,
-            "confidence": self.confidence,
-            "recommendation": self.recommendation,
-            "reasons": self.reasons,
-        }
-
-
-class CacheAnalyzer:
-    """Analyzes cache performance and provides recommendations.
-
-    Evaluates cache effectiveness based on hit rates, request patterns,
-    and memory usage, then provides actionable recommendations.
-
-    Example:
-        >>> analyzer = CacheAnalyzer()
-        >>> health = analyzer.analyze_cache("ast_parse")
-        >>> print(f"Health: {health.health}")
-        >>> print(f"Recommendation: {health.recommendation}")
-    """
-
-    @staticmethod
-    def analyze_cache(cache_name: str) -> CacheHealthScore | None:
-        """Analyze health of a specific cache.
-
-        Args:
-            cache_name: Name of cache to analyze
-
-        Returns:
-            CacheHealthScore with assessment and recommendations
-        """
-        monitor = CacheMonitor.get_instance()
-        stats = monitor.get_stats(cache_name)
-
-        if not stats:
-            return None
-
-        return CacheAnalyzer._calculate_health(stats)
-
-    @staticmethod
-    def analyze_all() -> dict[str, CacheHealthScore]:
-        """Analyze health of all caches.
-
-        Returns:
-            Dictionary mapping cache names to CacheHealthScore
-        """
-        monitor = CacheMonitor.get_instance()
-        all_stats = monitor.get_all_stats()
-
-        return {name: CacheAnalyzer._calculate_health(stats) for name, stats in all_stats.items()}
-
-    @staticmethod
-    def _calculate_health(stats: CacheStats) -> CacheHealthScore:
-        """Calculate health score for cache statistics.
-
-        Args:
-            stats: CacheStats to analyze
-
-        Returns:
-            CacheHealthScore with health assessment
-        """
-        hit_rate = stats.hit_rate
-        total_requests = stats.total_requests
-        utilization = stats.utilization
-
-        # Determine health based on hit rate and request count
-        if total_requests < 10:
-            # Low request count - low confidence
-            confidence = "low"
-            if hit_rate >= 0.8:
-                health = "excellent"
-            elif hit_rate >= 0.6:
-                health = "good"
-            else:
-                health = "fair"
-        elif total_requests < 100:
-            # Medium request count - medium confidence
-            confidence = "medium"
-            if hit_rate >= 0.7:
-                health = "excellent"
-            elif hit_rate >= 0.5:
-                health = "good"
-            elif hit_rate >= 0.3:
-                health = "fair"
-            else:
-                health = "poor"
-        else:
-            # High request count - high confidence
-            confidence = "high"
-            if hit_rate >= 0.6:
-                health = "excellent"
-            elif hit_rate >= 0.4:
-                health = "good"
-            elif hit_rate >= 0.2:
-                health = "fair"
-            else:
-                health = "poor"
-
-        # Generate reasons and recommendations
-        reasons = []
-        recommendation = ""
-
-        if hit_rate > 0.7:
-            reasons.append("Strong hit rate indicates good cache effectiveness")
-            if total_requests >= 100:
-                recommendation = (
-                    "Cache is performing well. Consider monitoring for memory usage as it grows."
-                )
-            else:
-                recommendation = "Cache shows promise with limited data. Continue monitoring."
-        elif hit_rate > 0.5:
-            reasons.append("Moderate hit rate suggests cache is somewhat effective")
-            recommendation = "Monitor for patterns. May benefit from adjusted cache key strategy."
-        elif hit_rate > 0.2:
-            reasons.append("Low hit rate indicates cache may not be effective for this pattern")
-            recommendation = "Review cache invalidation strategy or consider disabling if overhead exceeds benefit."
-        else:
-            reasons.append("Very low hit rate suggests cache is ineffective")
-            recommendation = "Strongly consider disabling this cache or redesigning cache key."
-
-        if utilization > 0.9 and stats.max_size > 0:
-            reasons.append("Cache is nearly full - may be evicting useful entries")
-            recommendation = (
-                f"{recommendation} Consider increasing cache size to {int(stats.max_size * 1.5)}."
-            )
-        elif utilization < 0.1 and stats.max_size > 0 and total_requests > 50:
-            reasons.append("Cache is underutilized - may be oversized")
-            recommendation = f"{recommendation} Consider reducing cache size to {max(1, int(stats.max_size * 0.5))}."
-
-        if total_requests > 1000 and hit_rate < 0.3:
-            reasons.append("High request volume with low hit rate suggests cache thrashing")
-            recommendation = "Cache invalidation may be too aggressive. Review cache lifetime."
-
-        return CacheHealthScore(
-            cache_name=stats.name,
-            hit_rate=hit_rate,
-            health=health,
-            confidence=confidence,
-            recommendation=recommendation,
-            reasons=reasons,
-        )
-
-
-class CacheReporter:
-    """Generates formatted cache performance reports.
-
-    Creates human-readable reports on cache metrics, health scores,
-    and recommendations for optimization.
-
-    Example:
-        >>> reporter = CacheReporter()
-        >>> print(reporter.generate_health_report())
-    """
-
-    @staticmethod
-    def generate_health_report(verbose: bool = False) -> str:
-        """Generate cache health report.
-
-        Args:
-            verbose: Include detailed metrics
-
-        Returns:
-            Formatted health report
-        """
-        analyzer = CacheAnalyzer()
-        health_scores = analyzer.analyze_all()
-
-        if not health_scores:
-            return "No caches registered for monitoring"
-
-        # Sort by health (excellent -> poor)
-        health_order = {"excellent": 0, "good": 1, "fair": 2, "poor": 3}
-        sorted_scores = sorted(
-            health_scores.values(),
-            key=lambda s: (health_order.get(s.health, 99), -s.hit_rate),
-        )
-
-        lines = ["=" * 80, "CACHE HEALTH REPORT", "=" * 80, ""]
-
-        for score in sorted_scores:
-            lines.append(f"Cache: {score.cache_name}")
-            lines.append("-" * 80)
-            lines.append(f"  Health:        {score.health.upper()}")
-            lines.append(f"  Confidence:    {score.confidence.upper()}")
-            lines.append(f"  Hit Rate:      {score.hit_rate:.1%}")
-            lines.append(f"  Recommendation: {score.recommendation}")
-
-            if verbose:
-                for reason in score.reasons:
-                    lines.append(f"    - {reason}")
-
-            lines.append("")
-
-        # Summary
-        excellent = sum(1 for s in health_scores.values() if s.health == "excellent")
-        good = sum(1 for s in health_scores.values() if s.health == "good")
-        fair = sum(1 for s in health_scores.values() if s.health == "fair")
-        poor = sum(1 for s in health_scores.values() if s.health == "poor")
-
-        lines.append("=" * 80)
-        lines.append("SUMMARY")
-        lines.append("=" * 80)
-        lines.append(f"  Total Caches:    {len(health_scores)}")
-        lines.append(f"  Excellent:       {excellent}")
-        lines.append(f"  Good:            {good}")
-        lines.append(f"  Fair:            {fair}")
-        lines.append(f"  Poor:            {poor}")
-        lines.append("=" * 80)
-
-        return "\n".join(lines)
-
-    @staticmethod
-    def generate_optimization_report() -> str:
-        """Generate cache optimization recommendations.
-
-        Returns:
-            Formatted optimization report
-        """
-        monitor = CacheMonitor.get_instance()
-        analyzer = CacheAnalyzer()
-
-        lines = ["=" * 80, "CACHE OPTIMIZATION OPPORTUNITIES", "=" * 80, ""]
-
-        underperformers = monitor.get_underperformers(threshold=0.3)
-        if underperformers:
-            lines.append("LOW-PERFORMING CACHES (hit rate < 30%):")
-            lines.append("-" * 80)
-            for stats in underperformers:
-                health = analyzer.analyze_cache(stats.name)
-                if health:
-                    lines.append(f"  {stats.name}: {health.recommendation}")
-            lines.append("")
-
-        high_performers = monitor.get_high_performers(threshold=0.7)
-        if high_performers:
-            lines.append("HIGH-PERFORMING CACHES (hit rate > 70%):")
-            lines.append("-" * 80)
-            for stats in high_performers:
-                lines.append(f"  {stats.name}: Performing well ({stats.hit_rate:.1%} hit rate)")
-            lines.append("")
-
-        lines.append("=" * 80)
-
-        return "\n".join(lines)
-
-    @staticmethod
-    def generate_full_report() -> str:
-        """Generate comprehensive cache report.
-
-        Returns:
-            Formatted comprehensive report
-        """
-        monitor = CacheMonitor.get_instance()
-
-        report_parts = [
-            "=" * 80,
-            "COMPREHENSIVE CACHE ANALYSIS REPORT",
-            "=" * 80,
-            "",
-            monitor.get_report(verbose=True),
-            "",
-            monitor.get_size_report(),
-            "",
-            CacheReporter.generate_health_report(verbose=True),
-            "",
-            CacheReporter.generate_optimization_report(),
-        ]
-
-        return "\n".join(report_parts)

empathy_os/cli/__init__.py

@@ -1,152 +0,0 @@
-"""Empathy Framework CLI - Refactored modular structure.
-
-Entry point for the empathy command-line interface.
-
-Copyright 2025 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-import argparse
-import sys
-
-from empathy_os.discovery import show_tip_if_available
-from empathy_os.logging_config import get_logger
-from empathy_os.platform_utils import setup_asyncio_policy
-
-logger = get_logger(__name__)
-
-
-def get_version() -> str:
-    """Get package version.
-
-    Returns:
-        Version string or "dev" if not installed
-    """
-    try:
-        from importlib.metadata import version
-
-        return version("empathy-framework")
-    except Exception:  # noqa: BLE001
-        return "dev"
-
-
-def main() -> int:
-    """Main CLI entry point.
-
-    This is the refactored CLI entry point that uses modular command
-    and parser organization instead of a monolithic 3,957-line file.
-
-    Returns:
-        Exit code (0 for success, non-zero for error)
-    """
-    # Windows async compatibility
-    setup_asyncio_policy()
-
-    # Create main parser
-    parser = argparse.ArgumentParser(
-        prog="empathy", description="Empathy Framework - Context-aware development automation"
-    )
-
-    # Add global flags
-    parser.add_argument("--version", action="version", version=f"empathy {get_version()}")
-
-    # Create subparsers
-    subparsers = parser.add_subparsers(
-        dest="command", title="commands", description="Available commands"
-    )
-
-    # Register all command parsers (modular!)
-    from .parsers import register_all_parsers
-
-    register_all_parsers(subparsers)
-
-    # TODO: Import and register remaining commands from cli.py
-    # This is a partial refactoring - additional commands still in cli.py
-    # For now, if command not found in new structure, fall back to old cli.py
-    #
-    # NOTE: Temporarily disabled to avoid conflicts with extracted commands.
-    # Commands that have been extracted:
-    #   - help, tier, info, patterns, status (Phase 1)
-    #   - workflow, inspect (run, inspect, export, import) (Phase 2)
-    # Once all commands are extracted, the old cli.py will be removed entirely.
-    #
-    # try:
-    #     from empathy_os import cli as old_cli
-    #     _register_legacy_commands(subparsers, old_cli)
-    # except ImportError:
-    #     pass  # Old cli.py not available or already moved
-
-    # Parse arguments
-    args = parser.parse_args()
-
-    # Execute command
-    if hasattr(args, "func"):
-        try:
-            result = args.func(args)
-
-            # Show discovery tips (except for dashboard/run)
-            if args.command and args.command not in ("dashboard", "run"):
-                try:
-                    show_tip_if_available(args.command)
-                except Exception:  # noqa: BLE001
-                    logger.debug("Discovery tip not available")
-
-            return result if result is not None else 0
-
-        except KeyboardInterrupt:
-            print("\n\n⚠️  Interrupted by user")
-            return 130
-
-        except Exception as e:  # noqa: BLE001
-            logger.exception(f"Unexpected error in command {args.command}")
-            print(f"\n❌ Error: {e}")
-            return 1
-
-    # No command specified
-    parser.print_help()
-    return 0
-
-
-def _register_legacy_commands(subparsers, old_cli):
-    """Temporarily register commands not yet extracted from old cli.py.
-
-    This function provides backward compatibility during the refactoring process.
-    As commands are extracted into the new structure, they should be removed
-    from this registration.
-
-    Args:
-        subparsers: ArgumentParser subparsers object
-        old_cli: Reference to old cli module
-
-    Note:
-        This is a TEMPORARY function that will be removed once all commands
-        are extracted from the monolithic cli.py file.
-    """
-    # Import command functions that haven't been extracted yet
-    try:
-        # Patterns commands
-        from empathy_os.cli import cmd_patterns_export, cmd_patterns_list, cmd_patterns_resolve
-
-        patterns_parser = subparsers.add_parser("patterns", help="Pattern management")
-        patterns_sub = patterns_parser.add_subparsers(dest="patterns_command")
-
-        p_list = patterns_sub.add_parser("list", help="List patterns")
-        p_list.set_defaults(func=cmd_patterns_list)
-
-        p_export = patterns_sub.add_parser("export", help="Export patterns")
-        p_export.add_argument("output", help="Output file")
-        p_export.set_defaults(func=cmd_patterns_export)
-
-        p_resolve = patterns_sub.add_parser("resolve", help="Resolve pattern")
-        p_resolve.add_argument("pattern_id", help="Pattern ID")
-        p_resolve.set_defaults(func=cmd_patterns_resolve)
-    except (ImportError, AttributeError):
-        pass  # Commands not available
-
-    # Add other legacy commands as needed...
-    # This list will shrink as commands are extracted
-
-
-# Preserve backward compatibility
-if __name__ == "__main__":
-    sys.exit(main())

empathy_os/cli/__main__.py

@@ -1,12 +0,0 @@
-"""CLI entry point for python -m empathy_os.cli execution.
-
-Copyright 2025 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-import sys
-
-from . import main
-
-if __name__ == "__main__":
-    sys.exit(main())

empathy_os/cli/commands/__init__.py

@@ -1 +0,0 @@
-"""CLI command implementations."""