oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/reporting/engine.py

@@ -88,99 +88,115 @@ class AnalysisEngine:
         Raises:
             ValueError: If input type cannot be determined.
         """
-        # If path provided, detect from extension
+        # Try path-based detection first
         if input_path is not None:
-            ext = input_path.suffix.lower()
+            path_type = self._detect_from_extension(input_path)
+            if path_type is not None:
+                return path_type
 
-            # Waveform formats
-            if ext in {".wfm", ".csv", ".npz", ".h5", ".hdf5", ".wav", ".tdms"}:
-                return InputType.WAVEFORM
-            # Digital formats
-            elif ext in {".vcd", ".sr"}:
-                return InputType.DIGITAL
-            # Packet formats
-            elif ext in {".pcap", ".pcapng"}:
-                return InputType.PCAP
-            # Binary formats
-            elif ext in {".bin", ".raw"}:
-                return InputType.BINARY
-            # S-parameter/Touchstone formats
-            elif ext in {".s1p", ".s2p", ".s3p", ".s4p", ".s5p", ".s6p", ".s7p", ".s8p"}:
-                return InputType.SPARAMS
-
-        # Detect from data object characteristics
+        # Fallback to data object characteristics
+        data_type = self._detect_from_data_object(data)
+        if data_type is not None:
+            return data_type
+
+        raise ValueError("Unable to determine input type from path or data characteristics")
+
+    def _detect_from_extension(self, input_path: Path) -> InputType | None:
+        """Detect input type from file extension."""
+        ext = input_path.suffix.lower()
+
+        # Waveform formats
+        if ext in {".wfm", ".csv", ".npz", ".h5", ".hdf5", ".wav", ".tdms"}:
+            return InputType.WAVEFORM
+
+        # Digital formats
+        if ext in {".vcd", ".sr"}:
+            return InputType.DIGITAL
+
+        # Packet formats
+        if ext in {".pcap", ".pcapng"}:
+            return InputType.PCAP
+
+        # Binary formats
+        if ext in {".bin", ".raw"}:
+            return InputType.BINARY
+
+        # S-parameter/Touchstone formats
+        if ext in {".s1p", ".s2p", ".s3p", ".s4p", ".s5p", ".s6p", ".s7p", ".s8p"}:
+            return InputType.SPARAMS
+
+        return None
+
+    def _detect_from_data_object(self, data: Any) -> InputType | None:
+        """Detect input type from data object characteristics."""
+        # SParameterData
         if hasattr(data, "s_matrix") and hasattr(data, "frequencies"):
-            # SParameterData
             return InputType.SPARAMS
-        elif hasattr(data, "data") and hasattr(data, "metadata"):
-            # WaveformTrace or DigitalTrace
+
+        # WaveformTrace or DigitalTrace
+        if hasattr(data, "data") and hasattr(data, "metadata"):
             if hasattr(data.metadata, "is_digital") and data.metadata.is_digital:
                 return InputType.DIGITAL
             return InputType.WAVEFORM
-        elif isinstance(data, bytes | bytearray):
+
+        # Raw binary data
+        if isinstance(data, bytes | bytearray):
             return InputType.BINARY
-        elif isinstance(data, list):
-            # Assume packet list
+
+        # Packet list
+        if isinstance(data, list):
             return InputType.PACKETS
-        elif isinstance(data, np.ndarray):
-            # Assume waveform
+
+        # NumPy array (assume waveform)
+        if isinstance(data, np.ndarray):
             return InputType.WAVEFORM
 
-        raise ValueError("Unable to determine input type from path or data characteristics")
+        return None
 
-    def run(
-        self,
-        input_path: Path | None = None,
-        data: Any = None,
-        progress_callback: Callable[[ProgressInfo], None] | None = None,
-    ) -> dict[str, Any]:
-        """Run comprehensive analysis on input data.
+    def _initialize_engine(self, input_path: Path | None) -> None:
+        """Initialize engine state for analysis run.
 
         Args:
-            input_path: Path to input file (or None for in-memory data).
-            data: Input data object (or None to load from input_path).
-            progress_callback: Optional callback for progress updates.
-
-        Returns:
-            Dictionary with keys:
-                - 'results': Dict mapping AnalysisDomain to analysis results
-                - 'errors': List of AnalysisError objects
-                - 'stats': Execution statistics dict
-
-        Raises:
-            ValueError: If neither input_path nor data provided.
-            FileNotFoundError: If input_path doesn't exist.
-
-        Example:
-            >>> def progress(info: ProgressInfo):
-            ...     print(f"{info.phase}: {info.percent:.1f}%")
-            >>> result = engine.run(input_path=Path("data.wfm"), progress_callback=progress)
+            input_path: Input file path (or None for in-memory data).
         """
-        if input_path is None and data is None:
-            raise ValueError("Must provide either input_path or data")
-
         self._start_time = time.time()
         self._input_path = input_path
-
-        # Initialize argument preparer with input path and default sample rate
         default_sample_rate = self.config.default_sample_rate or 1e6
         self._arg_preparer = ArgumentPreparer(
             input_path=input_path, default_sample_rate=default_sample_rate
         )
 
-        # Check available memory and adjust parallelism if needed
+    def _check_memory_and_adjust(self) -> None:
+        """Check available memory and adjust parallelism if needed."""
         from oscura.core.memory_guard import check_memory_available
 
-        min_required_mb = 500  # Minimum 500MB needed for analysis
+        min_required_mb = 500
         if not check_memory_available(min_required_mb):
             logger.warning(
                 f"Low memory available (< {min_required_mb} MB). "
                 f"Reducing parallel workers to conserve memory."
             )
-            # Temporarily reduce parallelism to conserve memory
             self.config.parallel_domains = False
 
-        # Phase 1: Load data
+    def _load_input_data(
+        self,
+        input_path: Path | None,
+        data: Any,
+        progress_callback: Callable[[ProgressInfo], None] | None,
+    ) -> Any:
+        """Load input data from file or validate in-memory data.
+
+        Args:
+            input_path: Path to input file (or None).
+            data: In-memory data (or None).
+            progress_callback: Progress callback.
+
+        Returns:
+            Loaded or provided data.
+
+        Raises:
+            FileNotFoundError: If file not found.
+        """
         if progress_callback:
             progress_callback(
                 ProgressInfo(
@@ -197,15 +213,22 @@ class AnalysisEngine:
         if data is None:
             if input_path is None or not input_path.exists():
                 raise FileNotFoundError(f"Input file not found: {input_path}")
-
-            # Load using oscura loaders
             from oscura.loaders import load
 
-            data = load(input_path)
+            return load(input_path)
+        return data
 
-        # Phase 2: Detect input type
-        input_type = self.detect_input_type(input_path, data)
+    def _report_detection(
+        self,
+        input_type: InputType,
+        progress_callback: Callable[[ProgressInfo], None] | None,
+    ) -> None:
+        """Report input type detection progress.
 
+        Args:
+            input_type: Detected input type.
+            progress_callback: Progress callback.
+        """
         if progress_callback:
             progress_callback(
                 ProgressInfo(
@@ -219,10 +242,21 @@ class AnalysisEngine:
                 )
             )
 
-        # Phase 3: Determine applicable domains
-        applicable_domains = get_available_analyses(input_type)
+    def _plan_analysis_domains(
+        self,
+        input_type: InputType,
+        progress_callback: Callable[[ProgressInfo], None] | None,
+    ) -> list[AnalysisDomain]:
+        """Determine enabled analysis domains.
+
+        Args:
+            input_type: Input data type.
+            progress_callback: Progress callback.
 
-        # Filter by configuration
+        Returns:
+            List of enabled domains.
+        """
+        applicable_domains = get_available_analyses(input_type)
         enabled_domains = [d for d in applicable_domains if self.config.is_domain_enabled(d)]
 
         if progress_callback:
@@ -237,80 +271,40 @@ class AnalysisEngine:
                     estimated_remaining_seconds=None,
                 )
             )
+        return enabled_domains
 
-        # Phase 4: Execute analyses
-        results: dict[AnalysisDomain, dict[str, Any]] = {}
-        errors: list[AnalysisError] = []
-
-        total_domains = len(enabled_domains)
+    def _execute_domains_parallel(
+        self,
+        enabled_domains: list[AnalysisDomain],
+        data: Any,
+        progress_callback: Callable[[ProgressInfo], None] | None,
+    ) -> tuple[dict[AnalysisDomain, dict[str, Any]], list[AnalysisError]]:
+        """Execute analysis domains in parallel.
 
-        # Execute domains in parallel if enabled and multiple domains exist
-        if self.config.parallel_domains and len(enabled_domains) > 1:
-            import concurrent.futures
+        Args:
+            enabled_domains: List of domains to analyze.
+            data: Input data.
+            progress_callback: Progress callback.
 
-            # Use ThreadPoolExecutor with bounded workers from config
-            max_workers = min(self.config.max_parallel_workers, len(enabled_domains))
+        Returns:
+            Tuple of (results dict, errors list).
+        """
+        import concurrent.futures
 
-            with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
-                # Submit all domain executions
-                futures = {
-                    executor.submit(self._execute_domain, domain, data): domain
-                    for domain in enabled_domains
-                }
+        results: dict[AnalysisDomain, dict[str, Any]] = {}
+        errors: list[AnalysisError] = []
+        total_domains = len(enabled_domains)
+        max_workers = min(self.config.max_parallel_workers, len(enabled_domains))
 
-                # Process results as they complete
-                for completed, future in enumerate(concurrent.futures.as_completed(futures), 1):
-                    domain = futures[future]
-                    domain_percent = 10.0 + (completed / total_domains) * 80.0
-
-                    if progress_callback:
-                        progress_callback(
-                            ProgressInfo(
-                                phase="analyzing",
-                                domain=domain,
-                                function=None,
-                                percent=domain_percent,
-                                message=f"Completed domain: {domain.value}",
-                                elapsed_seconds=time.time() - self._start_time,
-                                estimated_remaining_seconds=None,
-                            )
-                        )
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {
+                executor.submit(self._execute_domain, domain, data): domain
+                for domain in enabled_domains
+            }
 
-                    try:
-                        # Retrieve result with timeout
-                        timeout_seconds = self.config.timeout_per_analysis or 30.0
-                        domain_results, domain_errors = future.result(timeout=timeout_seconds * 10)
-                        if domain_results:
-                            results[domain] = domain_results
-                        errors.extend(domain_errors)
-                    except concurrent.futures.TimeoutError:
-                        logger.error(f"Domain {domain.value} exceeded timeout")
-                        errors.append(
-                            AnalysisError(
-                                domain=domain,
-                                function=f"{domain.value}.*",
-                                error_type="TimeoutError",
-                                error_message="Domain execution exceeded timeout",
-                                traceback=None,
-                                duration_ms=timeout_seconds * 10 * 1000,
-                            )
-                        )
-                    except Exception as e:
-                        logger.error(f"Domain {domain.value} failed: {e}")
-                        errors.append(
-                            AnalysisError(
-                                domain=domain,
-                                function=f"{domain.value}.*",
-                                error_type=type(e).__name__,
-                                error_message=str(e),
-                                traceback=traceback.format_exc(),
-                                duration_ms=0.0,
-                            )
-                        )
-        else:
-            # Sequential fallback (existing code)
-            for idx, domain in enumerate(enabled_domains):
-                domain_percent = 10.0 + (idx / total_domains) * 80.0
+            for completed, future in enumerate(concurrent.futures.as_completed(futures), 1):
+                domain = futures[future]
+                domain_percent = 10.0 + (completed / total_domains) * 80.0
 
                 if progress_callback:
                     progress_callback(
@@ -319,41 +313,134 @@ class AnalysisEngine:
                             domain=domain,
                             function=None,
                             percent=domain_percent,
-                            message=f"Analyzing domain: {domain.value}",
+                            message=f"Completed domain: {domain.value}",
                             elapsed_seconds=time.time() - self._start_time,
                             estimated_remaining_seconds=None,
                         )
                     )
 
-                domain_results, domain_errors = self._execute_domain(domain, data)
-                if domain_results:
-                    results[domain] = domain_results
-                errors.extend(domain_errors)
+                self._handle_domain_future(future, domain, results, errors)
 
-        # Phase 5: Complete
-        total_duration = time.time() - self._start_time
+        return results, errors
 
-        if progress_callback:
-            progress_callback(
-                ProgressInfo(
-                    phase="complete",
-                    domain=None,
-                    function=None,
-                    percent=100.0,
-                    message="Analysis complete",
-                    elapsed_seconds=total_duration,
-                    estimated_remaining_seconds=0.0,
+    def _handle_domain_future(
+        self,
+        future: Any,
+        domain: AnalysisDomain,
+        results: dict[AnalysisDomain, dict[str, Any]],
+        errors: list[AnalysisError],
+    ) -> None:
+        """Handle completed domain future.
+
+        Args:
+            future: Completed future.
+            domain: Domain being analyzed.
+            results: Results accumulator.
+            errors: Errors accumulator.
+        """
+        import concurrent.futures
+
+        try:
+            timeout_seconds = self.config.timeout_per_analysis or 30.0
+            domain_results, domain_errors = future.result(timeout=timeout_seconds * 10)
+            if domain_results:
+                results[domain] = domain_results
+            errors.extend(domain_errors)
+        except concurrent.futures.TimeoutError:
+            logger.error(f"Domain {domain.value} exceeded timeout")
+            errors.append(
+                AnalysisError(
+                    domain=domain,
+                    function=f"{domain.value}.*",
+                    error_type="TimeoutError",
+                    error_message="Domain execution exceeded timeout",
+                    traceback=None,
+                    duration_ms=timeout_seconds * 10 * 1000,
                 )
             )
+        except Exception as e:
+            logger.error(f"Domain {domain.value} failed: {e}")
+            errors.append(
+                AnalysisError(
+                    domain=domain,
+                    function=f"{domain.value}.*",
+                    error_type=type(e).__name__,
+                    error_message=str(e),
+                    traceback=traceback.format_exc(),
+                    duration_ms=0.0,
+                )
+            )
+
+    def _execute_domains_sequential(
+        self,
+        enabled_domains: list[AnalysisDomain],
+        data: Any,
+        progress_callback: Callable[[ProgressInfo], None] | None,
+    ) -> tuple[dict[AnalysisDomain, dict[str, Any]], list[AnalysisError]]:
+        """Execute analysis domains sequentially.
+
+        Args:
+            enabled_domains: List of domains to analyze.
+            data: Input data.
+            progress_callback: Progress callback.
+
+        Returns:
+            Tuple of (results dict, errors list).
+        """
+        results: dict[AnalysisDomain, dict[str, Any]] = {}
+        errors: list[AnalysisError] = []
+        total_domains = len(enabled_domains)
+
+        for idx, domain in enumerate(enabled_domains):
+            domain_percent = 10.0 + (idx / total_domains) * 80.0
+
+            if progress_callback:
+                progress_callback(
+                    ProgressInfo(
+                        phase="analyzing",
+                        domain=domain,
+                        function=None,
+                        percent=domain_percent,
+                        message=f"Analyzing domain: {domain.value}",
+                        elapsed_seconds=time.time() - self._start_time,
+                        estimated_remaining_seconds=None,
+                    )
+                )
+
+            domain_results, domain_errors = self._execute_domain(domain, data)
+            if domain_results:
+                results[domain] = domain_results
+            errors.extend(domain_errors)
+
+        return results, errors
+
+    def _calculate_statistics(
+        self,
+        results: dict[AnalysisDomain, dict[str, Any]],
+        errors: list[AnalysisError],
+        enabled_domains: list[AnalysisDomain],
+        input_type: InputType,
+        total_duration: float,
+    ) -> dict[str, Any]:
+        """Calculate execution statistics.
 
-        # Calculate statistics
+        Args:
+            results: Analysis results.
+            errors: Analysis errors.
+            enabled_domains: List of enabled domains.
+            input_type: Input data type.
+            total_duration: Total execution time.
+
+        Returns:
+            Statistics dictionary.
+        """
         total_analyses = sum(len(dr) for dr in results.values())
         successful_analyses = sum(
             1 for dr in results.values() for v in dr.values() if not isinstance(v, Exception)
         )
         failed_analyses = len(errors)
 
-        stats = {
+        return {
             "input_type": input_type.value,
             "total_domains": len(enabled_domains),
             "total_analyses": total_analyses,
@@ -365,6 +452,73 @@ class AnalysisEngine:
             "duration_seconds": total_duration,
         }
 
+    def run(
+        self,
+        input_path: Path | None = None,
+        data: Any = None,
+        progress_callback: Callable[[ProgressInfo], None] | None = None,
+    ) -> dict[str, Any]:
+        """Run comprehensive analysis on input data.
+
+        Args:
+            input_path: Path to input file (or None for in-memory data).
+            data: Input data object (or None to load from input_path).
+            progress_callback: Optional callback for progress updates.
+
+        Returns:
+            Dictionary with keys:
+                - 'results': Dict mapping AnalysisDomain to analysis results
+                - 'errors': List of AnalysisError objects
+                - 'stats': Execution statistics dict
+
+        Raises:
+            ValueError: If neither input_path nor data provided.
+            FileNotFoundError: If input_path doesn't exist.
+
+        Example:
+            >>> def progress(info: ProgressInfo):
+            ...     print(f"{info.phase}: {info.percent:.1f}%")
+            >>> result = engine.run(input_path=Path("data.wfm"), progress_callback=progress)
+        """
+        if input_path is None and data is None:
+            raise ValueError("Must provide either input_path or data")
+
+        self._initialize_engine(input_path)
+        self._check_memory_and_adjust()
+        data = self._load_input_data(input_path, data, progress_callback)
+        input_type = self.detect_input_type(input_path, data)
+        self._report_detection(input_type, progress_callback)
+        enabled_domains = self._plan_analysis_domains(input_type, progress_callback)
+
+        # Execute analyses (parallel or sequential)
+        if self.config.parallel_domains and len(enabled_domains) > 1:
+            results, errors = self._execute_domains_parallel(
+                enabled_domains, data, progress_callback
+            )
+        else:
+            results, errors = self._execute_domains_sequential(
+                enabled_domains, data, progress_callback
+            )
+
+        # Finalize
+        total_duration = time.time() - self._start_time
+        if progress_callback:
+            progress_callback(
+                ProgressInfo(
+                    phase="complete",
+                    domain=None,
+                    function=None,
+                    percent=100.0,
+                    message="Analysis complete",
+                    elapsed_seconds=total_duration,
+                    estimated_remaining_seconds=0.0,
+                )
+            )
+
+        stats = self._calculate_statistics(
+            results, errors, enabled_domains, input_type, total_duration
+        )
+
         return {
             "results": results,
             "errors": errors,
@@ -797,7 +951,7 @@ class AnalysisEngine:
             Result with quality score attached (if applicable).
         """
         try:
-            from oscura.quality import score_analysis_result
+            from oscura.validation.quality import score_analysis_result
 
             # Extract raw data array for quality assessment
             if hasattr(data, "data"):