devsquad 3.6.0__py3-none-any.whl

scripts/collaboration/output_slicer.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+EnhancedWorker Output Slicing (P1-3)
+
+Adds incremental output capability to EnhancedWorker:
+  - Splits large outputs into configurable slices
+  - Writes intermediate slices to scratchpad for real-time monitoring
+  - Provides progress tracking during long-running tasks
+
+Spec reference: SPEC_V35_Agent_Skills_Quality_Framework.md Section 7.3
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class OutputSlice:
+    """A single slice of output with metadata."""
+    slice_number: int
+    total_slices: int
+    content: str
+    line_start: int
+    line_end: int
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "slice_number": self.slice_number,
+            "total_slices": self.total_slices,
+            "line_range": f"{self.line_start}-{self.line_end}",
+            "content_length": len(self.content),
+            "timestamp": self.timestamp,
+        }
+
+
+@dataclass
+class SlicedOutput:
+    """Complete sliced output result."""
+    original_output: str
+    slices: List[OutputSlice] = field(default_factory=list)
+    total_lines: int = 0
+    total_slices: int = 0
+    was_sliced: bool = False
+
+    def get_full_output(self) -> str:
+        if not self.was_sliced:
+            return self.original_output
+        return "\n".join(s.content for s in self.slices)
+
+    def get_slice(self, index: int) -> Optional[OutputSlice]:
+        if 0 <= index < len(self.slices):
+            return self.slices[index]
+        return None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "total_lines": self.total_lines,
+            "total_slices": self.total_slices,
+            "was_sliced": self.was_sliced,
+            "slices": [s.to_dict() for s in self.slices],
+        }
+
+
+class OutputSlicer:
+    """
+    Splits large outputs into manageable slices.
+
+    Usage:
+        slicer = OutputSlicer(max_slice_lines=100)
+        result = slicer.slice_output(large_text)
+        print(f"Total: {result.total_slices} slices")
+        for s in result.slices:
+            print(s.content)
+    """
+
+    DEFAULT_MAX_SLICE_LINES = 100
+    SLICE_HEADER_TEMPLATE = "\n--- Slice {current}/{total} (lines {start}-{end}) ---\n"
+
+    def __init__(
+        self,
+        max_slice_lines: int = DEFAULT_MAX_SLICE_LINES,
+        include_headers: bool = True,
+        write_to_scratchpad: bool = False,
+        scratchpad=None,
+    ):
+        """
+        Initialize output slicer.
+
+        Args:
+            max_slice_lines: Maximum lines per slice (default: 100)
+            include_headers: Add slice headers to each slice
+            write_to_scratchpad: Write intermediate slices to scratchpad
+            scratchpad: Scratchpad instance for writing slices
+        """
+        self.max_slice_lines = max(max_slice_lines, 10)  # Minimum 10 lines
+        self.include_headers = include_headers
+        self.write_to_scratchpad = write_to_scratchpad
+        self._scratchpad = scratchpad
+
+    def slice_output(
+        self,
+        output: str,
+        task_id: Optional[str] = None,
+        role_id: Optional[str] = None,
+    ) -> SlicedOutput:
+        """
+        Split output into slices if it exceeds max_slice_lines.
+
+        Args:
+            output: The full output text to potentially slice
+            task_id: Optional task identifier for scratchpad keys
+            role_id: Optional role identifier for scratchpad keys
+
+        Returns:
+            SlicedOutput with all metadata
+        """
+        if not output or not output.strip():
+            return SlicedOutput(
+                original_output=output,
+                total_lines=0,
+                total_slices=0,
+                was_sliced=False,
+            )
+
+        lines = output.split('\n')
+        total_lines = len(lines)
+
+        if total_lines <= self.max_slice_lines:
+            return SlicedOutput(
+                original_output=output,
+                total_lines=total_lines,
+                total_slices=1,
+                was_sliced=False,
+            )
+
+        # Calculate number of slices needed
+        total_slices = (total_lines + self.max_slice_lines - 1) // self.max_slice_lines
+
+        slices = []
+        for i in range(0, total_lines, self.max_slice_lines):
+            slice_num = i // self.max_slice_lines + 1
+            line_start = i + 1
+            line_end = min(i + self.max_slice_lines, total_lines)
+            slice_lines = lines[i:i + self.max_slice_lines]
+
+            if self.include_headers:
+                header = self.SLICE_HEADER_TEMPLATE.format(
+                    current=slice_num,
+                    total=total_slices,
+                    start=line_start,
+                    end=line_end,
+                )
+                content = header + '\n'.join(slice_lines)
+            else:
+                content = '\n'.join(slice_lines)
+
+            output_slice = OutputSlice(
+                slice_number=slice_num,
+                total_slices=total_slices,
+                content=content,
+                line_start=line_start,
+                line_end=line_end,
+            )
+            slices.append(output_slice)
+
+            # Write to scratchpad if enabled
+            if self.write_to_scratchpad and self._scratchpad is not None:
+                try:
+                    key = f"{role_id or 'unknown'}/slice_{slice_num}"
+                    if task_id:
+                        key = f"{task_id}/{key}"
+                    self._scratchpad.write(key, content)
+                except Exception as e:
+                    logger.debug("Failed to write slice %d to scratchpad: %s", slice_num, e)
+
+        return SlicedOutput(
+            original_output=output,
+            slices=slices,
+            total_lines=total_lines,
+            total_slices=total_slices,
+            was_sliced=True,
+        )
+
+    def batch_slice_outputs(
+        self,
+        outputs: List[str],
+        task_ids: Optional[List[str]] = None,
+    ) -> List[SlicedOutput]:
+        """
+        Slice multiple outputs at once.
+
+        Args:
+            outputs: List of output strings to slice
+            task_ids: Optional list of task IDs (must match outputs length)
+
+        Returns:
+            List of SlicedOutput results
+        """
+        results = []
+        for i, output in enumerate(outputs):
+            tid = task_ids[i] if task_ids and i < len(task_ids) else None
+            result = self.slice_output(output, task_id=tid)
+            results.append(result)
+        return results
+
+
+def create_default_slicer() -> OutputSlicer:
+    """Create slicer with default settings (100 lines per slice)."""
+    return OutputSlicer()
+
+
+def create_compact_slicer() -> OutputSlicer:
+    """Create compact slicer for small context windows (50 lines)."""
+    return OutputSlicer(max_slice_lines=50)
+
+
+def create_large_slicer() -> OutputSlicer:
+    """Create large slicer for detailed outputs (200 lines)."""
+    return OutputSlicer(max_slice_lines=200)

scripts/collaboration/performance_monitor.py

@@ -0,0 +1,462 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Performance Monitoring Module
+
+Tracks and analyzes system performance metrics:
+- Response time monitoring
+- Resource usage tracking
+- Performance bottleneck detection
+- Real-time metrics dashboard
+
+Usage:
+    from scripts.collaboration.performance_monitor import monitor_performance
+
+    @monitor_performance(name="llm_call")
+    def call_llm(prompt: str):
+        return response
+
+    from scripts.collaboration.performance_monitor import get_monitor
+    stats = get_monitor().get_stats()
+"""
+
+import time
+import logging
+from typing import Callable, Dict, Any, List, Optional
+from functools import wraps
+from dataclasses import dataclass, field
+from datetime import datetime
+from collections import defaultdict, deque
+
+try:
+    import psutil
+    _PSUTIL_AVAILABLE = True
+except ImportError:
+    _PSUTIL_AVAILABLE = False
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PerformanceMetric:
+    """Performance metric data structure."""
+    name: str
+    start_time: float
+    end_time: float
+    duration: float
+    cpu_percent: float
+    memory_mb: float
+    success: bool
+    error: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "duration_ms": self.duration * 1000,
+            "cpu_percent": self.cpu_percent,
+            "memory_mb": self.memory_mb,
+            "success": self.success,
+            "error": self.error,
+            "timestamp": datetime.fromtimestamp(self.start_time).isoformat()
+        }
+
+
+@dataclass
+class FunctionStats:
+    """Function execution statistics."""
+    name: str
+    call_count: int = 0
+    success_count: int = 0
+    failure_count: int = 0
+    total_duration: float = 0.0
+    min_duration: float = float('inf')
+    max_duration: float = 0.0
+    recent_metrics: deque = field(default_factory=lambda: deque(maxlen=100))
+
+    def add_metric(self, metric: PerformanceMetric):
+        """Add a performance metric."""
+        self.call_count += 1
+        if metric.success:
+            self.success_count += 1
+        else:
+            self.failure_count += 1
+
+        self.total_duration += metric.duration
+        self.min_duration = min(self.min_duration, metric.duration)
+        self.max_duration = max(self.max_duration, metric.duration)
+        self.recent_metrics.append(metric)
+
+    @property
+    def avg_duration(self) -> float:
+        """Average execution duration."""
+        return self.total_duration / self.call_count if self.call_count > 0 else 0.0
+
+    @property
+    def success_rate(self) -> float:
+        """Success rate."""
+        return self.success_count / self.call_count if self.call_count > 0 else 0.0
+
+    @property
+    def p95_duration(self) -> float:
+        """P95 response time."""
+        if not self.recent_metrics:
+            return 0.0
+        durations = sorted([m.duration for m in self.recent_metrics])
+        idx = int(len(durations) * 0.95)
+        return durations[idx] if idx < len(durations) else durations[-1]
+
+    @property
+    def p99_duration(self) -> float:
+        """P99 response time."""
+        if not self.recent_metrics:
+            return 0.0
+        durations = sorted([m.duration for m in self.recent_metrics])
+        idx = int(len(durations) * 0.99)
+        return durations[idx] if idx < len(durations) else durations[-1]
+
+
+def _get_cpu_percent() -> float:
+    """Safely get CPU percent, returns 0.0 if psutil unavailable."""
+    if not _PSUTIL_AVAILABLE:
+        return 0.0
+    try:
+        return psutil.Process().cpu_percent()
+    except Exception:
+        return 0.0
+
+
+def _get_memory_mb() -> float:
+    """Safely get memory usage in MB, returns 0.0 if psutil unavailable."""
+    if not _PSUTIL_AVAILABLE:
+        return 0.0
+    try:
+        return psutil.Process().memory_info().rss / 1024 / 1024
+    except Exception:
+        return 0.0
+
+
+class PerformanceMonitor:
+    """
+    Performance Monitor
+
+    Features:
+    - Automatic function execution time tracking
+    - CPU and memory usage monitoring
+    - P95/P99 response time calculation
+    - Performance bottleneck detection
+    - Performance report generation
+    """
+
+    def __init__(self, max_history: int = 1000):
+        """
+        Initialize performance monitor.
+
+        Args:
+            max_history: Maximum number of historical records to retain
+        """
+        self.function_stats: Dict[str, FunctionStats] = defaultdict(
+            lambda: FunctionStats(name="")
+        )
+        self.all_metrics: deque = deque(maxlen=max_history)
+        self.start_time = time.time()
+
+    def record_metric(self, metric: PerformanceMetric):
+        """Record a performance metric."""
+        self.all_metrics.append(metric)
+
+        if metric.name not in self.function_stats:
+            self.function_stats[metric.name] = FunctionStats(name=metric.name)
+
+        self.function_stats[metric.name].add_metric(metric)
+
+    def monitor(self, name: str):
+        """
+        Decorator: monitor function performance.
+
+        Args:
+            name: Function name identifier
+        """
+        def decorator(func: Callable) -> Callable:
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                start_time = time.time()
+                start_cpu = _get_cpu_percent()
+                start_memory = _get_memory_mb()
+
+                success = True
+                error = None
+
+                try:
+                    result = func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    success = False
+                    error = str(e)
+                    raise
+                finally:
+                    end_time = time.time()
+                    end_cpu = _get_cpu_percent()
+                    end_memory = _get_memory_mb()
+
+                    metric = PerformanceMetric(
+                        name=name,
+                        start_time=start_time,
+                        end_time=end_time,
+                        duration=end_time - start_time,
+                        cpu_percent=(start_cpu + end_cpu) / 2,
+                        memory_mb=(start_memory + end_memory) / 2,
+                        success=success,
+                        error=error
+                    )
+
+                    self.record_metric(metric)
+
+            return wrapper
+        return decorator
+
+    def get_stats(self, function_name: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Get statistics (compatible with MonitorProvider Protocol).
+
+        Args:
+            function_name: If specified, return only that function's stats
+
+        Returns:
+            Statistics dictionary
+        """
+        if function_name:
+            if function_name not in self.function_stats:
+                return {}
+
+            stats = self.function_stats[function_name]
+            return {
+                "name": stats.name,
+                "call_count": stats.call_count,
+                "success_count": stats.success_count,
+                "failure_count": stats.failure_count,
+                "success_rate": f"{stats.success_rate * 100:.1f}%",
+                "avg_duration_ms": stats.avg_duration * 1000,
+                "min_duration_ms": stats.min_duration * 1000,
+                "max_duration_ms": stats.max_duration * 1000,
+                "p95_duration_ms": stats.p95_duration * 1000,
+                "p99_duration_ms": stats.p99_duration * 1000,
+            }
+
+        llm_calls = [s for name, s in self.function_stats.items() if name.startswith("llm_call:")]
+        agent_executions = [s for name, s in self.function_stats.items() if name.startswith("agent:")]
+
+        total_llm_calls = sum(s.call_count for s in llm_calls)
+        total_agent_executions = sum(s.call_count for s in agent_executions)
+
+        avg_llm_duration = (
+            sum(s.total_duration for s in llm_calls) / total_llm_calls
+            if total_llm_calls > 0 else 0.0
+        )
+
+        avg_agent_duration = (
+            sum(s.total_duration for s in agent_executions) / total_agent_executions
+            if total_agent_executions > 0 else 0.0
+        )
+
+        return {
+            "total_llm_calls": total_llm_calls,
+            "total_agent_executions": total_agent_executions,
+            "avg_llm_duration": avg_llm_duration,
+            "avg_agent_duration": avg_agent_duration,
+            "total_tokens": 0,
+            "uptime_seconds": time.time() - self.start_time,
+            "total_metrics": len(self.all_metrics),
+            "functions": {
+                name: {
+                    "call_count": stats.call_count,
+                    "success_rate": f"{stats.success_rate * 100:.1f}%",
+                    "avg_duration_ms": stats.avg_duration * 1000,
+                    "p95_duration_ms": stats.p95_duration * 1000,
+                }
+                for name, stats in self.function_stats.items()
+            }
+        }
+
+    def get_slowest_functions(self, limit: int = 10) -> List[Dict[str, Any]]:
+        """Get the slowest functions by average duration."""
+        sorted_funcs = sorted(
+            self.function_stats.values(),
+            key=lambda s: s.avg_duration,
+            reverse=True
+        )[:limit]
+
+        return [
+            {
+                "name": stats.name,
+                "avg_duration_ms": stats.avg_duration * 1000,
+                "call_count": stats.call_count,
+                "p95_duration_ms": stats.p95_duration * 1000,
+            }
+            for stats in sorted_funcs
+        ]
+
+    def get_bottlenecks(self, threshold_ms: float = 1000) -> List[Dict[str, Any]]:
+        """
+        Detect performance bottlenecks.
+
+        Args:
+            threshold_ms: Threshold in milliseconds; functions above this are bottlenecks
+
+        Returns:
+            List of bottleneck entries
+        """
+        bottlenecks = []
+
+        for name, stats in self.function_stats.items():
+            if stats.avg_duration * 1000 > threshold_ms:
+                bottlenecks.append({
+                    "name": name,
+                    "avg_duration_ms": stats.avg_duration * 1000,
+                    "p95_duration_ms": stats.p95_duration * 1000,
+                    "call_count": stats.call_count,
+                    "severity": "high" if stats.avg_duration * 1000 > threshold_ms * 2 else "medium"
+                })
+
+        return sorted(bottlenecks, key=lambda x: x["avg_duration_ms"], reverse=True)
+
+    def get_recent_errors(self, limit: int = 10) -> List[Dict[str, Any]]:
+        """Get recent error entries."""
+        errors = [m for m in self.all_metrics if not m.success]
+        return [m.to_dict() for m in list(errors)[-limit:]]
+
+    def record_llm_call(
+        self,
+        backend: str,
+        model: str,
+        duration: float,
+        token_count: int,
+        success: bool,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Record an LLM API call (implements MonitorProvider Protocol)."""
+        metric_name = f"llm_call:{backend}:{model}"
+
+        metric = PerformanceMetric(
+            name=metric_name,
+            start_time=time.time() - duration,
+            end_time=time.time(),
+            duration=duration,
+            cpu_percent=_get_cpu_percent(),
+            memory_mb=_get_memory_mb(),
+            success=success,
+            error=metadata.get("error") if metadata else None
+        )
+
+        self.record_metric(metric)
+
+    def record_agent_execution(
+        self,
+        agent_role: str,
+        task: str,
+        duration: float,
+        success: bool,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Record an agent execution (implements MonitorProvider Protocol)."""
+        metric_name = f"agent:{agent_role}"
+
+        metric = PerformanceMetric(
+            name=metric_name,
+            start_time=time.time() - duration,
+            end_time=time.time(),
+            duration=duration,
+            cpu_percent=_get_cpu_percent(),
+            memory_mb=_get_memory_mb(),
+            success=success,
+            error=metadata.get("error") if metadata else None
+        )
+
+        self.record_metric(metric)
+
+    def generate_report(self, output_path: str) -> None:
+        """Generate performance report to file (implements MonitorProvider Protocol)."""
+        try:
+            report = self.export_report()
+            with open(output_path, 'w', encoding='utf-8') as f:
+                f.write(report)
+            logger.info("Performance report generated: %s", output_path)
+        except Exception as e:
+            logger.error("Failed to generate report: %s", e)
+            raise IOError(f"Failed to generate report: {e}")
+
+    def is_available(self) -> bool:
+        """Check if monitoring is available (implements MonitorProvider Protocol)."""
+        return True
+
+    def export_report(self) -> str:
+        """Export performance report as Markdown string."""
+        stats = self.get_stats()
+        slowest = self.get_slowest_functions(5)
+        bottlenecks = self.get_bottlenecks()
+        errors = self.get_recent_errors(5)
+
+        report = f"""# Performance Monitoring Report
+
+**Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+**Uptime**: {stats['uptime_seconds']:.0f} seconds
+**Total Metrics**: {stats['total_metrics']}
+
+## Overall Statistics
+
+| Function | Calls | Success Rate | Avg Duration | P95 Duration |
+|----------|-------|--------------|--------------|--------------|
+"""
+
+        for name, func_stats in stats['functions'].items():
+            report += f"| {name} | {func_stats['call_count']} | {func_stats['success_rate']} | {func_stats['avg_duration_ms']:.1f}ms | {func_stats['p95_duration_ms']:.1f}ms |\n"
+
+        if slowest:
+            report += "\n## Slowest Functions\n\n"
+            for i, func in enumerate(slowest, 1):
+                report += f"{i}. **{func['name']}**: {func['avg_duration_ms']:.1f}ms avg ({func['call_count']} calls)\n"
+
+        if bottlenecks:
+            report += "\n## Performance Bottlenecks\n\n"
+            for bottleneck in bottlenecks:
+                report += f"- **{bottleneck['name']}** ({bottleneck['severity']}): {bottleneck['avg_duration_ms']:.1f}ms avg\n"
+
+        if errors:
+            report += "\n## Recent Errors\n\n"
+            for error in errors:
+                report += f"- **{error['name']}** at {error['timestamp']}: {error['error']}\n"
+
+        return report
+
+
+_monitor_instance: Optional[PerformanceMonitor] = None
+
+
+def get_monitor() -> PerformanceMonitor:
+    """Get or create global monitor instance."""
+    global _monitor_instance
+    if _monitor_instance is None:
+        _monitor_instance = PerformanceMonitor()
+    return _monitor_instance
+
+
+def monitor_performance(name: str):
+    """
+    Decorator: monitor function performance.
+
+    Args:
+        name: Function name identifier
+
+    Example:
+        @monitor_performance("llm_call")
+        def call_llm(prompt: str):
+            return response
+    """
+    monitor = get_monitor()
+    return monitor.monitor(name)
+
+
+def reset_monitor():
+    """Reset global monitor instance (mainly for testing)."""
+    global _monitor_instance
+    _monitor_instance = None