PraisonAI 3.0.0__py3-none-any.whl

praisonai/cli/features/doctor/formatters.py

@@ -0,0 +1,310 @@
+"""
+Output formatters for the Doctor CLI module.
+
+Provides text and JSON formatting with secret redaction.
+"""
+
+import json
+import re
+import sys
+from typing import Any, Dict, List, Optional, TextIO
+from .models import CheckResult, CheckStatus, DoctorReport, ReportSummary
+
+
+# Patterns for detecting secrets
+SECRET_PATTERNS = [
+    re.compile(r'(sk-[a-zA-Z0-9]{20,})', re.IGNORECASE),  # OpenAI
+    re.compile(r'(sk-ant-[a-zA-Z0-9-]{20,})', re.IGNORECASE),  # Anthropic
+    re.compile(r'(AIza[a-zA-Z0-9_-]{35})', re.IGNORECASE),  # Google
+    re.compile(r'(tvly-[a-zA-Z0-9]{20,})', re.IGNORECASE),  # Tavily
+    re.compile(r'(xai-[a-zA-Z0-9]{20,})', re.IGNORECASE),  # xAI
+    re.compile(r'([a-zA-Z0-9_-]*api[_-]?key[a-zA-Z0-9_-]*=\s*["\']?[a-zA-Z0-9_-]{16,})', re.IGNORECASE),
+    re.compile(r'([a-zA-Z0-9_-]*token[a-zA-Z0-9_-]*=\s*["\']?[a-zA-Z0-9_-]{16,})', re.IGNORECASE),
+    re.compile(r'([a-zA-Z0-9_-]*secret[a-zA-Z0-9_-]*=\s*["\']?[a-zA-Z0-9_-]{16,})', re.IGNORECASE),
+    re.compile(r'(password\s*=\s*["\']?[^\s"\']{8,})', re.IGNORECASE),
+]
+
+# Known API key environment variable names
+API_KEY_ENV_VARS = [
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "GOOGLE_API_KEY",
+    "GEMINI_API_KEY",
+    "TAVILY_API_KEY",
+    "EXA_API_KEY",
+    "COHERE_API_KEY",
+    "HUGGINGFACE_API_KEY",
+    "HF_TOKEN",
+    "LANGFUSE_PUBLIC_KEY",
+    "LANGFUSE_SECRET_KEY",
+    "LANGSMITH_API_KEY",
+    "AGENTOPS_API_KEY",
+    "WANDB_API_KEY",
+    "DATADOG_API_KEY",
+    "BRAINTRUST_API_KEY",
+    "YDC_API_KEY",
+]
+
+
+def redact_secrets(text: str, show_prefix_suffix: bool = False) -> str:
+    """
+    Redact secrets from text.
+    
+    Args:
+        text: Text to redact
+        show_prefix_suffix: If True, show first 4 and last 4 chars
+        
+    Returns:
+        Text with secrets redacted
+    """
+    if not text:
+        return text
+    
+    result = text
+    
+    for pattern in SECRET_PATTERNS:
+        def replace_match(match):
+            secret = match.group(1)
+            if show_prefix_suffix and len(secret) > 12:
+                return f"{secret[:4]}...{secret[-4:]}"
+            return "***REDACTED***"
+        result = pattern.sub(replace_match, result)
+    
+    return result
+
+
+def redact_dict(data: Dict[str, Any], show_prefix_suffix: bool = False) -> Dict[str, Any]:
+    """
+    Recursively redact secrets from a dictionary.
+    
+    Args:
+        data: Dictionary to redact
+        show_prefix_suffix: If True, show first 4 and last 4 chars
+        
+    Returns:
+        Dictionary with secrets redacted
+    """
+    result = {}
+    for key, value in data.items():
+        if isinstance(value, str):
+            # Check if key suggests it's a secret
+            key_lower = key.lower()
+            if any(s in key_lower for s in ["key", "token", "secret", "password", "credential"]):
+                if show_prefix_suffix and len(value) > 12:
+                    result[key] = f"{value[:4]}...{value[-4:]}"
+                else:
+                    result[key] = "***REDACTED***"
+            else:
+                result[key] = redact_secrets(value, show_prefix_suffix)
+        elif isinstance(value, dict):
+            result[key] = redact_dict(value, show_prefix_suffix)
+        elif isinstance(value, list):
+            result[key] = [
+                redact_dict(v, show_prefix_suffix) if isinstance(v, dict)
+                else redact_secrets(v, show_prefix_suffix) if isinstance(v, str)
+                else v
+                for v in value
+            ]
+        else:
+            result[key] = value
+    return result
+
+
+class BaseFormatter:
+    """Base class for output formatters."""
+    
+    def __init__(
+        self,
+        no_color: bool = False,
+        quiet: bool = False,
+        redact: bool = True,
+        show_prefix_suffix: bool = False,
+    ):
+        self.no_color = no_color or not sys.stdout.isatty()
+        self.quiet = quiet
+        self.redact = redact
+        self.show_prefix_suffix = show_prefix_suffix
+    
+    def format_report(self, report: DoctorReport) -> str:
+        """Format a complete report."""
+        raise NotImplementedError
+    
+    def format_result(self, result: CheckResult) -> str:
+        """Format a single check result."""
+        raise NotImplementedError
+    
+    def write(self, report: DoctorReport, output: Optional[TextIO] = None) -> None:
+        """Write formatted report to output."""
+        output = output or sys.stdout
+        output.write(self.format_report(report))
+        if not self.format_report(report).endswith("\n"):
+            output.write("\n")
+
+
+class TextFormatter(BaseFormatter):
+    """Text formatter with optional color support."""
+    
+    # ANSI color codes
+    COLORS = {
+        "reset": "\033[0m",
+        "bold": "\033[1m",
+        "dim": "\033[2m",
+        "red": "\033[31m",
+        "green": "\033[32m",
+        "yellow": "\033[33m",
+        "blue": "\033[34m",
+        "cyan": "\033[36m",
+        "white": "\033[37m",
+    }
+    
+    STATUS_COLORS = {
+        CheckStatus.PASS: "green",
+        CheckStatus.WARN: "yellow",
+        CheckStatus.FAIL: "red",
+        CheckStatus.SKIP: "dim",
+        CheckStatus.ERROR: "red",
+    }
+    
+    STATUS_SYMBOLS = {
+        CheckStatus.PASS: "✓",
+        CheckStatus.WARN: "⚠",
+        CheckStatus.FAIL: "✗",
+        CheckStatus.SKIP: "○",
+        CheckStatus.ERROR: "✗",
+    }
+    
+    def _color(self, text: str, color: str) -> str:
+        """Apply color to text if colors are enabled."""
+        if self.no_color:
+            return text
+        return f"{self.COLORS.get(color, '')}{text}{self.COLORS['reset']}"
+    
+    def _status_symbol(self, status: CheckStatus) -> str:
+        """Get colored status symbol."""
+        symbol = self.STATUS_SYMBOLS.get(status, "?")
+        color = self.STATUS_COLORS.get(status, "white")
+        return self._color(symbol, color)
+    
+    def format_result(self, result: CheckResult) -> str:
+        """Format a single check result."""
+        symbol = self._status_symbol(result.status)
+        message = result.message
+        if self.redact:
+            message = redact_secrets(message, self.show_prefix_suffix)
+        
+        line = f"{symbol} {result.title}: {message}"
+        
+        if result.details and not self.quiet:
+            details = result.details
+            if self.redact:
+                details = redact_secrets(details, self.show_prefix_suffix)
+            line += f"\n    {self._color(details, 'dim')}"
+        
+        if result.remediation and result.status in (CheckStatus.FAIL, CheckStatus.ERROR):
+            line += f"\n    {self._color('Fix:', 'yellow')} {result.remediation}"
+        
+        return line
+    
+    def format_summary(self, summary: ReportSummary, strict: bool = False) -> str:
+        """Format the summary section."""
+        parts = []
+        
+        if summary.passed > 0:
+            parts.append(self._color(f"{summary.passed} passed", "green"))
+        if summary.warnings > 0:
+            color = "red" if strict else "yellow"
+            parts.append(self._color(f"{summary.warnings} warnings", color))
+        if summary.failed > 0:
+            parts.append(self._color(f"{summary.failed} failed", "red"))
+        if summary.skipped > 0:
+            parts.append(self._color(f"{summary.skipped} skipped", "dim"))
+        if summary.errors > 0:
+            parts.append(self._color(f"{summary.errors} errors", "red"))
+        
+        return f"{summary.total} checks: " + ", ".join(parts)
+    
+    def format_report(self, report: DoctorReport) -> str:
+        """Format a complete report."""
+        lines = []
+        
+        # Header
+        if not self.quiet:
+            header = f"PraisonAI Doctor v{report.version}"
+            lines.append(self._color(header, "bold"))
+            lines.append("━" * 70)
+        
+        # Results
+        for result in report.results:
+            lines.append(self.format_result(result))
+        
+        # Summary
+        if not self.quiet:
+            lines.append("━" * 70)
+        lines.append(self.format_summary(report.summary))
+        
+        # Duration
+        if not self.quiet and report.duration_ms > 0:
+            lines.append(self._color(f"Completed in {report.duration_ms:.0f}ms", "dim"))
+        
+        return "\n".join(lines)
+
+
+class JsonFormatter(BaseFormatter):
+    """JSON formatter with deterministic output."""
+    
+    def format_result(self, result: CheckResult) -> str:
+        """Format a single check result as JSON."""
+        data = result.to_dict()
+        if self.redact:
+            data = redact_dict(data, self.show_prefix_suffix)
+        return json.dumps(data, indent=2, sort_keys=True)
+    
+    def format_report(self, report: DoctorReport) -> str:
+        """Format a complete report as JSON."""
+        data = report.to_dict()
+        if self.redact:
+            data = redact_dict(data, self.show_prefix_suffix)
+        
+        # Ensure deterministic ordering
+        return json.dumps(data, indent=2, sort_keys=True)
+    
+    def write(self, report: DoctorReport, output: Optional[TextIO] = None) -> None:
+        """Write formatted report to output."""
+        output = output or sys.stdout
+        output.write(self.format_report(report))
+        output.write("\n")
+
+
+def get_formatter(
+    format_type: str = "text",
+    no_color: bool = False,
+    quiet: bool = False,
+    redact: bool = True,
+    show_prefix_suffix: bool = False,
+) -> BaseFormatter:
+    """
+    Get a formatter instance.
+    
+    Args:
+        format_type: "text" or "json"
+        no_color: Disable ANSI colors
+        quiet: Minimal output
+        redact: Redact secrets
+        show_prefix_suffix: Show partial secrets
+        
+    Returns:
+        Formatter instance
+    """
+    if format_type == "json":
+        return JsonFormatter(
+            no_color=True,  # JSON never has colors
+            quiet=quiet,
+            redact=redact,
+            show_prefix_suffix=show_prefix_suffix,
+        )
+    return TextFormatter(
+        no_color=no_color,
+        quiet=quiet,
+        redact=redact,
+        show_prefix_suffix=show_prefix_suffix,
+    )

praisonai/cli/features/doctor/handler.py

@@ -0,0 +1,397 @@
+"""
+Doctor CLI handler for PraisonAI.
+
+Provides the main DoctorHandler class that integrates with the CLI.
+"""
+
+import argparse
+import sys
+from typing import List, Optional
+
+from ..base import CommandHandler
+from .models import CheckCategory, DoctorConfig, DoctorReport
+from .engine import DoctorEngine
+from .registry import get_registry
+from .formatters import get_formatter
+
+
+class DoctorHandler(CommandHandler):
+    """
+    Handler for the 'praisonai doctor' command.
+    
+    Provides comprehensive health checks and diagnostics.
+    """
+    
+    @property
+    def feature_name(self) -> str:
+        return "doctor"
+    
+    def get_actions(self) -> List[str]:
+        return [
+            "env",
+            "config", 
+            "tools",
+            "db",
+            "mcp",
+            "obs",
+            "skills",
+            "memory",
+            "permissions",
+            "network",
+            "performance",
+            "ci",
+            "selftest",
+        ]
+    
+    def _register_checks(self) -> None:
+        """Register all doctor checks."""
+        from .checks import register_all_checks
+        register_all_checks()
+    
+    def _parse_args(self, args: List[str]) -> argparse.Namespace:
+        """Parse doctor command arguments."""
+        parser = argparse.ArgumentParser(
+            prog="praisonai doctor",
+            description="PraisonAI health checks and diagnostics",
+        )
+        
+        # Subcommand
+        parser.add_argument(
+            "subcommand",
+            nargs="?",
+            choices=self.get_actions() + [None],
+            help="Subcommand to run (default: run all fast checks)",
+        )
+        
+        # Global flags
+        parser.add_argument(
+            "--json",
+            action="store_true",
+            help="Output in JSON format",
+        )
+        parser.add_argument(
+            "--format",
+            choices=["text", "json"],
+            default="text",
+            help="Output format (default: text)",
+        )
+        parser.add_argument(
+            "--output", "-o",
+            type=str,
+            help="Write report to file",
+        )
+        parser.add_argument(
+            "--deep",
+            action="store_true",
+            help="Enable deeper probes (DB connects, network checks)",
+        )
+        parser.add_argument(
+            "--timeout",
+            type=float,
+            default=10.0,
+            help="Per-check timeout in seconds (default: 10)",
+        )
+        parser.add_argument(
+            "--strict",
+            action="store_true",
+            help="Treat warnings as failures",
+        )
+        parser.add_argument(
+            "--quiet", "-q",
+            action="store_true",
+            help="Minimal output",
+        )
+        parser.add_argument(
+            "--no-color",
+            action="store_true",
+            help="Disable ANSI colors",
+        )
+        parser.add_argument(
+            "--only",
+            type=str,
+            help="Only run these check IDs (comma-separated)",
+        )
+        parser.add_argument(
+            "--skip",
+            type=str,
+            help="Skip these check IDs (comma-separated)",
+        )
+        parser.add_argument(
+            "--list-checks",
+            action="store_true",
+            help="List available check IDs",
+        )
+        parser.add_argument(
+            "--version",
+            action="store_true",
+            help="Show doctor module version",
+        )
+        
+        # Subcommand-specific flags
+        parser.add_argument(
+            "--show-keys",
+            action="store_true",
+            help="Show masked API key values (env subcommand)",
+        )
+        parser.add_argument(
+            "--require",
+            type=str,
+            help="Require these env vars (comma-separated)",
+        )
+        parser.add_argument(
+            "--file", "-f",
+            type=str,
+            help="Config file to validate (config subcommand)",
+        )
+        parser.add_argument(
+            "--schema",
+            action="store_true",
+            help="Print expected schema (config subcommand)",
+        )
+        parser.add_argument(
+            "--dsn",
+            type=str,
+            help="Database DSN (db subcommand)",
+        )
+        parser.add_argument(
+            "--provider",
+            type=str,
+            help="Provider name (db/obs subcommand)",
+        )
+        parser.add_argument(
+            "--read-only",
+            action="store_true",
+            default=True,
+            help="Read-only mode for DB checks (default: true)",
+        )
+        parser.add_argument(
+            "--name",
+            type=str,
+            help="Name filter (mcp/tools subcommand)",
+        )
+        parser.add_argument(
+            "--category",
+            type=str,
+            help="Category filter (tools subcommand)",
+        )
+        parser.add_argument(
+            "--all",
+            action="store_true",
+            dest="all_checks",
+            help="Show all items (tools subcommand)",
+        )
+        parser.add_argument(
+            "--missing-only",
+            action="store_true",
+            help="Show only missing items (tools subcommand)",
+        )
+        parser.add_argument(
+            "--list-tools",
+            action="store_true",
+            help="List MCP tools (mcp subcommand)",
+        )
+        parser.add_argument(
+            "--path",
+            type=str,
+            help="Path to check (skills subcommand)",
+        )
+        parser.add_argument(
+            "--all-installed",
+            action="store_true",
+            help="Check all installed skills",
+        )
+        parser.add_argument(
+            "--budget-ms",
+            type=int,
+            help="Import time budget in ms (performance subcommand)",
+        )
+        parser.add_argument(
+            "--top",
+            type=int,
+            default=10,
+            dest="top_n",
+            help="Number of top items to show (default: 10)",
+        )
+        parser.add_argument(
+            "--fail-fast",
+            action="store_true",
+            help="Stop on first failure (ci subcommand)",
+        )
+        parser.add_argument(
+            "--mock",
+            action="store_true",
+            default=True,
+            help="Use mock mode (selftest, default: true)",
+        )
+        parser.add_argument(
+            "--live",
+            action="store_true",
+            help="Use live API calls (selftest)",
+        )
+        parser.add_argument(
+            "--model",
+            type=str,
+            help="Model to use for selftest",
+        )
+        parser.add_argument(
+            "--save-report",
+            action="store_true",
+            help="Save selftest report",
+        )
+        
+        return parser.parse_args(args)
+    
+    def _build_config(self, args: argparse.Namespace) -> DoctorConfig:
+        """Build DoctorConfig from parsed arguments."""
+        return DoctorConfig(
+            deep=args.deep,
+            timeout=args.timeout if args.deep else min(args.timeout, 10.0),
+            strict=args.strict,
+            quiet=args.quiet,
+            no_color=args.no_color,
+            format="json" if args.json else args.format,
+            output_path=args.output,
+            only=args.only.split(",") if args.only else [],
+            skip=args.skip.split(",") if args.skip else [],
+            show_keys=args.show_keys,
+            require_keys=args.require.split(",") if args.require else [],
+            config_file=args.file,
+            dsn=args.dsn,
+            provider=args.provider,
+            read_only=args.read_only,
+            mock=args.mock and not args.live,
+            live=args.live,
+            model=args.model,
+            budget_ms=args.budget_ms,
+            top_n=args.top_n,
+            fail_fast=args.fail_fast,
+            list_tools=args.list_tools,
+            all_checks=args.all_checks,
+            missing_only=args.missing_only,
+            name=args.name,
+            category=args.category,
+            path=args.path,
+            save_report=args.save_report,
+        )
+    
+    def _get_categories_for_subcommand(self, subcommand: Optional[str]) -> Optional[List[CheckCategory]]:
+        """Get check categories for a subcommand."""
+        category_map = {
+            "env": [CheckCategory.ENVIRONMENT],
+            "config": [CheckCategory.CONFIG],
+            "tools": [CheckCategory.TOOLS],
+            "db": [CheckCategory.DATABASE],
+            "mcp": [CheckCategory.MCP],
+            "obs": [CheckCategory.OBSERVABILITY],
+            "skills": [CheckCategory.SKILLS],
+            "memory": [CheckCategory.MEMORY],
+            "permissions": [CheckCategory.PERMISSIONS],
+            "network": [CheckCategory.NETWORK],
+            "performance": [CheckCategory.PERFORMANCE],
+            "selftest": [CheckCategory.SELFTEST],
+            "ci": None,  # CI runs all checks
+        }
+        return category_map.get(subcommand)
+    
+    def execute(self, action: str, action_args: List[str], **kwargs) -> int:
+        """
+        Execute the doctor command.
+        
+        Args:
+            action: The subcommand or empty string
+            action_args: Additional arguments
+            
+        Returns:
+            Exit code (0=pass, 1=fail, 2=error)
+        """
+        # Combine action and action_args for parsing
+        all_args = [action] + action_args if action and action != "help" else action_args
+        
+        try:
+            args = self._parse_args(all_args)
+        except SystemExit:
+            return 0  # Help was shown
+        
+        # Handle special flags
+        if args.version:
+            from . import __version__
+            print(f"PraisonAI Doctor v{__version__}")
+            return 0
+        
+        # Register all checks
+        self._register_checks()
+        
+        if args.list_checks:
+            registry = get_registry()
+            print(registry.list_checks_text())
+            return 0
+        
+        # Build config
+        config = self._build_config(args)
+        
+        # Handle CI mode
+        if args.subcommand == "ci":
+            config.format = "json"
+            config.no_color = True
+            config.quiet = True
+        
+        # Get categories for subcommand
+        categories = self._get_categories_for_subcommand(args.subcommand)
+        
+        # Run doctor
+        engine = DoctorEngine(config)
+        report = engine.run(categories=categories)
+        
+        # Format output
+        formatter = get_formatter(
+            format_type=config.format,
+            no_color=config.no_color,
+            quiet=config.quiet,
+            show_prefix_suffix=config.show_keys,
+        )
+        
+        # Write output
+        if config.output_path:
+            with open(config.output_path, "w") as f:
+                formatter.write(report, f)
+            if not config.quiet:
+                print(f"Report written to: {config.output_path}")
+        else:
+            formatter.write(report, sys.stdout)
+        
+        return report.exit_code
+    
+    def run(self, args: List[str]) -> int:
+        """
+        Run the doctor command from CLI.
+        
+        Args:
+            args: Command line arguments after 'doctor'
+            
+        Returns:
+            Exit code
+        """
+        if not args:
+            return self.execute("", [])
+        
+        action = args[0] if args else ""
+        action_args = args[1:] if len(args) > 1 else []
+        
+        return self.execute(action, action_args)
+
+
+def run_doctor(args: Optional[List[str]] = None) -> int:
+    """
+    Convenience function to run doctor from CLI.
+    
+    Args:
+        args: Command line arguments (default: sys.argv[1:])
+        
+    Returns:
+        Exit code
+    """
+    if args is None:
+        args = sys.argv[1:]
+    
+    handler = DoctorHandler()
+    return handler.run(args)