oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/guidance/wizard.py

@@ -181,40 +181,22 @@ class AnalysisWizard:
         """
         self._predefined_answers = answers
 
-    def run(
-        self,
-        *,
-        preview_callback: Callable[[Any], None] | None = None,
-    ) -> WizardResult:
-        """Run the analysis wizard.
-
-        Guides user through analysis steps, auto-skipping where confident,
-        showing progress, and providing live previews.
+    def _execute_characterization_step(self, preview_callback: Callable[[Any], None] | None) -> Any:
+        """Execute signal characterization step.
 
         Args:
-            preview_callback: Optional callback for step previews.
+            preview_callback: Optional callback for step preview.
 
         Returns:
-            WizardResult with analysis summary and findings.
+            Characterization result object with signal_type and confidence.
 
         Example:
-            >>> wizard = AnalysisWizard(trace)
-            >>> result = wizard.run()
-            >>> print(result.summary)
-
-        References:
-            DISC-006: Interactive Analysis Wizard
+            >>> result = wizard._execute_characterization_step(None)
+            >>> print(result.signal_type)
         """
-        from oscura.discovery import (
-            assess_data_quality,
-            characterize_signal,
-            decode_protocol,
-            find_anomalies,
-        )
-        from oscura.guidance import suggest_next_steps
+        from oscura.discovery import characterize_signal
 
-        # Step 1: Auto-characterization
-        step1 = WizardStep(
+        step = WizardStep(
             number=1,
             id="characterization",
             question="What type of signal are you analyzing?",
@@ -228,31 +210,46 @@ class AnalysisWizard:
             skip_if_confident=False,
         )
 
-        # Always do auto-characterization first
         char_result = characterize_signal(self.trace)
-        step1.confidence_before = 0.0
-        step1.confidence_after = char_result.confidence
+        step.confidence_before = 0.0
+        step.confidence_after = char_result.confidence
         self._current_state["characterization"] = char_result
 
         if self.interactive and char_result.confidence < self.auto_detect_threshold:
-            # Ask user to confirm
-            step1.user_response = self._predefined_answers.get("signal_type", step1.default)
+            step.user_response = self._predefined_answers.get("signal_type", step.default)
             self.questions_asked += 1
         else:
-            # Auto-detected with high confidence
             signal_type = getattr(char_result, "signal_type", "Unknown")
-            step1.user_response = f"Auto-detected: {signal_type}"
+            step.user_response = f"Auto-detected: {signal_type}"
             self.questions_skipped += 1
 
-        self.step_history.append(step1)
+        self.step_history.append(step)
         self.steps_completed += 1
 
-        # Preview callback
         if preview_callback and self.enable_preview:
             preview_callback(char_result)
 
-        # Step 2: Quality assessment
-        step2 = WizardStep(
+        return char_result
+
+    def _execute_quality_assessment_step(
+        self, char_result: Any, preview_callback: Callable[[Any], None] | None
+    ) -> Any:
+        """Execute data quality assessment step.
+
+        Args:
+            char_result: Result from characterization step.
+            preview_callback: Optional callback for step preview.
+
+        Returns:
+            Quality assessment result with status and confidence.
+
+        Example:
+            >>> quality = wizard._execute_quality_assessment_step(char_result, None)
+            >>> print(quality.status)
+        """
+        from oscura.discovery import assess_data_quality
+
+        step = WizardStep(
             number=2,
             id="quality",
             question="Check data quality?",
@@ -262,98 +259,159 @@ class AnalysisWizard:
         )
 
         quality = assess_data_quality(self.trace)
-        step2.confidence_before = char_result.confidence
-        step2.confidence_after = quality.confidence
+        step.confidence_before = char_result.confidence
+        step.confidence_after = quality.confidence
         self._current_state["quality"] = quality
 
         if self.interactive and self.questions_asked < self.max_questions:
-            step2.user_response = self._predefined_answers.get("check_quality", "Yes")
-            if step2.user_response == "Yes":
+            step.user_response = self._predefined_answers.get("check_quality", "Yes")
+            if step.user_response == "Yes":
                 self.questions_asked += 1
         else:
-            step2.user_response = "Skipped (auto-assessed)"
+            step.user_response = "Skipped (auto-assessed)"
             self.questions_skipped += 1
 
-        self.step_history.append(step2)
+        self.step_history.append(step)
         self.steps_completed += 1
 
         if preview_callback and self.enable_preview:
             preview_callback(quality)
 
-        # Step 3: Protocol decode (if applicable)
+        return quality
+
+    def _execute_protocol_decode_step(
+        self, char_result: Any, preview_callback: Callable[[Any], None] | None
+    ) -> Any | None:
+        """Execute protocol decoding step if applicable.
+
+        Args:
+            char_result: Result from characterization step.
+            preview_callback: Optional callback for step preview.
+
+        Returns:
+            Decode result if protocol detected, None otherwise.
+
+        Example:
+            >>> decode = wizard._execute_protocol_decode_step(char_result, None)
+            >>> if decode:
+            ...     print(len(decode.data))
+        """
+        from oscura.discovery import decode_protocol
+
         decode_result = None
-        if hasattr(char_result, "signal_type") and char_result.confidence >= 0.7:
-            signal_type = char_result.signal_type.lower()
-
-            if any(proto in signal_type for proto in ["uart", "spi", "i2c", "can"]):
-                step3 = WizardStep(
-                    number=3,
-                    id="decode",
-                    question=f"Auto-detected {char_result.signal_type}. Decode data?",
-                    options=["Yes", "No"],
-                    default="Yes",
-                    skip_if_confident=True,
-                )
-
-                if self.interactive and self.questions_asked < self.max_questions:
-                    step3.user_response = self._predefined_answers.get("decode_data", "Yes")
-                    if step3.user_response == "Yes":
-                        decode_result = decode_protocol(self.trace)
-                        self._current_state["decode"] = decode_result
-                        self.questions_asked += 1
-                else:
-                    # Auto-decode
-                    decode_result = decode_protocol(self.trace)
-                    self._current_state["decode"] = decode_result
-                    step3.user_response = "Auto-decoded"
-                    self.questions_skipped += 1
-
-                step3.confidence_before = char_result.confidence
-                step3.confidence_after = decode_result.overall_confidence if decode_result else 0.0
-
-                self.step_history.append(step3)
-                self.steps_completed += 1
-
-                if preview_callback and self.enable_preview and decode_result:
-                    preview_callback(decode_result)
-
-        # Step 4: Anomaly detection (if quality issues)
+
+        if not (hasattr(char_result, "signal_type") and char_result.confidence >= 0.7):
+            return decode_result
+
+        signal_type = char_result.signal_type.lower()
+        if not any(proto in signal_type for proto in ["uart", "spi", "i2c", "can"]):
+            return decode_result
+
+        step = WizardStep(
+            number=3,
+            id="decode",
+            question=f"Auto-detected {char_result.signal_type}. Decode data?",
+            options=["Yes", "No"],
+            default="Yes",
+            skip_if_confident=True,
+        )
+
+        if self.interactive and self.questions_asked < self.max_questions:
+            step.user_response = self._predefined_answers.get("decode_data", "Yes")
+            if step.user_response == "Yes":
+                decode_result = decode_protocol(self.trace)
+                self._current_state["decode"] = decode_result
+                self.questions_asked += 1
+        else:
+            decode_result = decode_protocol(self.trace)
+            self._current_state["decode"] = decode_result
+            step.user_response = "Auto-decoded"
+            self.questions_skipped += 1
+
+        step.confidence_before = char_result.confidence
+        step.confidence_after = decode_result.overall_confidence if decode_result else 0.0
+
+        self.step_history.append(step)
+        self.steps_completed += 1
+
+        if preview_callback and self.enable_preview and decode_result:
+            preview_callback(decode_result)
+
+        return decode_result
+
+    def _execute_anomaly_detection_step(
+        self, quality: Any, preview_callback: Callable[[Any], None] | None
+    ) -> Any | None:
+        """Execute anomaly detection step if quality issues exist.
+
+        Args:
+            quality: Result from quality assessment step.
+            preview_callback: Optional callback for step preview.
+
+        Returns:
+            Anomaly detection results if quality issues found, None otherwise.
+
+        Example:
+            >>> anomalies = wizard._execute_anomaly_detection_step(quality, None)
+            >>> if anomalies:
+            ...     print(len(anomalies))
+        """
+        from oscura.discovery import find_anomalies
+
         anomalies = None
-        if quality.status in ["WARNING", "FAIL"]:
-            step4 = WizardStep(
-                number=self.steps_completed + 1,
-                id="anomalies",
-                question="Quality concerns detected. Check for anomalies?",
-                options=["Yes", "No"],
-                default="Yes",
-            )
-
-            if self.interactive and self.questions_asked < self.max_questions:
-                step4.user_response = self._predefined_answers.get("check_anomalies", "Yes")
-                if step4.user_response == "Yes":
-                    anomalies = find_anomalies(self.trace)
-                    self._current_state["anomalies"] = anomalies
-                    self.questions_asked += 1
-            else:
-                # Auto-check
+
+        if quality.status not in ["WARNING", "FAIL"]:
+            return anomalies
+
+        step = WizardStep(
+            number=self.steps_completed + 1,
+            id="anomalies",
+            question="Quality concerns detected. Check for anomalies?",
+            options=["Yes", "No"],
+            default="Yes",
+        )
+
+        if self.interactive and self.questions_asked < self.max_questions:
+            step.user_response = self._predefined_answers.get("check_anomalies", "Yes")
+            if step.user_response == "Yes":
                 anomalies = find_anomalies(self.trace)
                 self._current_state["anomalies"] = anomalies
-                step4.user_response = "Auto-checked"
-                self.questions_skipped += 1
+                self.questions_asked += 1
+        else:
+            anomalies = find_anomalies(self.trace)
+            self._current_state["anomalies"] = anomalies
+            step.user_response = "Auto-checked"
+            self.questions_skipped += 1
 
-            self.step_history.append(step4)
-            self.steps_completed += 1
+        self.step_history.append(step)
+        self.steps_completed += 1
 
-            if preview_callback and self.enable_preview and anomalies:
-                preview_callback(anomalies)
+        if preview_callback and self.enable_preview and anomalies:
+            preview_callback(anomalies)
 
-        # Get recommendations for next steps
-        recommendations = suggest_next_steps(
-            self.trace,
-            current_state=self._current_state,
-        )
+        return anomalies
+
+    def _build_summary(
+        self, char_result: Any, quality: Any, decode_result: Any | None, anomalies: Any | None
+    ) -> str:
+        """Build wizard result summary from analysis steps.
+
+        Args:
+            char_result: Characterization result.
+            quality: Quality assessment result.
+            decode_result: Protocol decode result (optional).
+            anomalies: Anomaly detection results (optional).
 
-        # Build summary
+        Returns:
+            Multi-line summary string.
+
+        Example:
+            >>> summary = wizard._build_summary(char, quality, decode, anomalies)
+            >>> print(summary)
+            Signal type: UART
+            Quality: Good
+            Decoded: 1024 bytes
+        """
         summary_parts = []
 
         if hasattr(char_result, "signal_type") and char_result.signal_type:
@@ -377,9 +435,47 @@ class AnalysisWizard:
             if critical > 0:
                 summary_parts.append(f"Anomalies: {critical} critical issues")
 
-        summary = "\n".join(summary_parts)
+        return "\n".join(summary_parts)
+
+    def run(
+        self,
+        *,
+        preview_callback: Callable[[Any], None] | None = None,
+    ) -> WizardResult:
+        """Run the analysis wizard.
+
+        Guides user through analysis steps, auto-skipping where confident,
+        showing progress, and providing live previews.
+
+        Args:
+            preview_callback: Optional callback for step previews.
+
+        Returns:
+            WizardResult with analysis summary and findings.
+
+        Example:
+            >>> wizard = AnalysisWizard(trace)
+            >>> result = wizard.run()
+            >>> print(result.summary)
+
+        References:
+            DISC-006: Interactive Analysis Wizard
+        """
+        from oscura.guidance import suggest_next_steps
+
+        # Execute analysis steps
+        char_result = self._execute_characterization_step(preview_callback)
+        quality = self._execute_quality_assessment_step(char_result, preview_callback)
+        decode_result = self._execute_protocol_decode_step(char_result, preview_callback)
+        anomalies = self._execute_anomaly_detection_step(quality, preview_callback)
+
+        # Generate recommendations and results
+        recommendations = suggest_next_steps(
+            self.trace,
+            current_state=self._current_state,
+        )
 
-        # Session duration
+        summary = self._build_summary(char_result, quality, decode_result, anomalies)
         self.session_duration_seconds = (datetime.now() - self._start_time).total_seconds()
 
         return WizardResult(

oscura/hardware/__init__.py

@@ -0,0 +1,19 @@
+"""Hardware abstraction layer analysis.
+
+This module provides tools for analyzing hardware abstraction layers,
+register access patterns, and peripheral drivers in firmware binaries.
+"""
+
+from oscura.hardware.hal_detector import (
+    HALAnalysisResult,
+    HALDetector,
+    Peripheral,
+    RegisterAccess,
+)
+
+__all__ = [
+    "HALAnalysisResult",
+    "HALDetector",
+    "Peripheral",
+    "RegisterAccess",
+]

oscura/{acquisition → hardware/acquisition}/__init__.py

@@ -11,7 +11,7 @@ The Source protocol enables polymorphic data acquisition:
 All sources implement the same interface, making them interchangeable:
 
 Example:
-    >>> from oscura.acquisition import FileSource, HardwareSource, SyntheticSource
+    >>> from oscura.hardware.acquisition import FileSource, HardwareSource, SyntheticSource
     >>> from oscura import SignalBuilder
     >>>
     >>> # All sources use the same interface
@@ -135,9 +135,9 @@ class Source(Protocol):
 
 
 # Import concrete implementations
-from oscura.acquisition.file import FileSource
-from oscura.acquisition.hardware import HardwareSource
-from oscura.acquisition.synthetic import SyntheticSource
+from oscura.hardware.acquisition.file import FileSource
+from oscura.hardware.acquisition.hardware import HardwareSource
+from oscura.hardware.acquisition.synthetic import SyntheticSource
 
 __all__ = [
     "FileSource",

oscura/{acquisition → hardware/acquisition}/file.py

@@ -5,7 +5,7 @@ the unified Source protocol. FileSource makes file loading consistent with all
 other acquisition methods (hardware, synthetic).
 
 Example:
-    >>> from oscura.acquisition import FileSource
+    >>> from oscura.hardware.acquisition import FileSource
     >>>
     >>> # Basic usage
     >>> source = FileSource("capture.wfm")
@@ -153,7 +153,7 @@ class FileSource:
 
         # Try lazy/chunked loading if available
         try:
-            from oscura.streaming import load_trace_chunks
+            from oscura.utils.streaming import load_trace_chunks
 
             # load_trace_chunks expects Path-like and chunk_size
             yield from load_trace_chunks(self.path, chunk_size=chunk_size)

oscura/{acquisition → hardware/acquisition}/hardware.py

@@ -11,7 +11,7 @@ Supported Hardware:
     - PyVISA: Oscilloscopes and instruments (requires pyvisa)
 
 Example:
-    >>> from oscura.acquisition import HardwareSource
+    >>> from oscura.hardware.acquisition import HardwareSource
     >>>
     >>> # SocketCAN source
     >>> with HardwareSource.socketcan("can0", bitrate=500000) as source:
@@ -48,9 +48,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from oscura.acquisition.saleae import SaleaeSource
-    from oscura.acquisition.socketcan import SocketCANSource
-    from oscura.acquisition.visa import VISASource
+    from oscura.hardware.acquisition.saleae import SaleaeSource
+    from oscura.hardware.acquisition.socketcan import SocketCANSource
+    from oscura.hardware.acquisition.visa import VISASource
 
 
 class HardwareSource:
@@ -107,7 +107,7 @@ class HardwareSource:
             Requires python-can library: pip install oscura[automotive]
             Linux only - uses SocketCAN kernel module.
         """
-        from oscura.acquisition.socketcan import SocketCANSource
+        from oscura.hardware.acquisition.socketcan import SocketCANSource
 
         return SocketCANSource(interface=interface, bitrate=bitrate, **kwargs)
 
@@ -142,7 +142,7 @@ class HardwareSource:
             Requires saleae library: pip install saleae
             Supports Logic 8, Logic Pro 8, Logic Pro 16.
         """
-        from oscura.acquisition.saleae import SaleaeSource
+        from oscura.hardware.acquisition.saleae import SaleaeSource
 
         return SaleaeSource(device_id=device_id, **kwargs)
 
@@ -178,7 +178,7 @@ class HardwareSource:
             Requires pyvisa and pyvisa-py: pip install pyvisa pyvisa-py
             Supports Tektronix, Keysight, Rigol, and other SCPI oscilloscopes.
         """
-        from oscura.acquisition.visa import VISASource
+        from oscura.hardware.acquisition.visa import VISASource
 
         return VISASource(resource=resource, **kwargs)
 

oscura/{acquisition → hardware/acquisition}/saleae.py

@@ -8,7 +8,7 @@ directly from the hardware, returning WaveformTrace (analog) or DigitalTrace
 (digital) depending on channel configuration.
 
 Example:
-    >>> from oscura.acquisition import HardwareSource
+    >>> from oscura.hardware.acquisition import HardwareSource
     >>>
     >>> # Basic digital acquisition
     >>> with HardwareSource.saleae() as source:
@@ -41,10 +41,17 @@ References:
 
 from __future__ import annotations
 
+import time
 from collections.abc import Iterator
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
+# Optional dependency - import at module level for mocking in tests
+try:
+    import saleae
+except ImportError:
+    saleae = None  # type: ignore[assignment]
+
 if TYPE_CHECKING:
     from oscura.core.types import Trace
 
@@ -88,7 +95,7 @@ class SaleaeSource:
         """
         self.device_id = device_id
         self.kwargs = kwargs
-        self.saleae = None
+        self.saleae: Any = None  # Saleae connection object (dynamic import)
         self._closed = False
 
         # Configuration
@@ -107,12 +114,10 @@ class SaleaeSource:
         if self.saleae is not None:
             return
 
-        try:
-            import saleae
-        except ImportError as e:
+        if saleae is None:
             raise ImportError(
                 "Saleae source requires saleae library. Install with: pip install saleae"
-            ) from e
+            )
 
         try:
             self.saleae = saleae.Saleae()
@@ -164,12 +169,12 @@ class SaleaeSource:
         self._ensure_connection()
 
         # Set sample rate
-        self.saleae.set_sample_rate_by_minimum(sample_rate)  # type: ignore[union-attr]
+        self.saleae.set_sample_rate_by_minimum(sample_rate)
 
         # Enable/disable channels
         for ch in range(16):  # Max 16 digital channels
             if ch in self.digital_channels:
-                self.saleae.set_capture_pretrigger_buffer_size(  # type: ignore[union-attr]
+                self.saleae.set_capture_pretrigger_buffer_size(
                     int(sample_rate * duration), is_set=True
                 )
 
@@ -204,15 +209,13 @@ class SaleaeSource:
         acquisition_start = datetime.now()
 
         # Start capture
-        self.saleae.capture_start()  # type: ignore[union-attr]
+        self.saleae.capture_start()
 
         # Wait for capture to complete
-        import time
-
         time.sleep(self.duration)
 
         # Stop capture
-        self.saleae.capture_stop()  # type: ignore[union-attr]
+        self.saleae.capture_stop()
 
         # Export data
         # Note: Actual Saleae API would save to file, then we'd load it.

oscura/{acquisition → hardware/acquisition}/socketcan.py

@@ -9,7 +9,7 @@ CAN ID represented as a separate digital channel. This enables protocol analysis
 and reverse engineering of CAN bus communications.
 
 Example:
-    >>> from oscura.acquisition import HardwareSource
+    >>> from oscura.hardware.acquisition import HardwareSource
     >>>
     >>> # Basic usage
     >>> with HardwareSource.socketcan("can0", bitrate=500000) as source:

oscura/{acquisition → hardware/acquisition}/streaming.py

@@ -8,8 +8,8 @@ Planned features:
 - Buffering and backpressure management
 
 Example (Future):
-    >>> from oscura.acquisition import HardwareSource
-    >>> from oscura.acquisition.streaming import LiveProcessor
+    >>> from oscura.hardware.acquisition import HardwareSource
+    >>> from oscura.hardware.acquisition.streaming import LiveProcessor
     >>>
     >>> # Real-time streaming from hardware
     >>> processor = LiveProcessor(

oscura/{acquisition → hardware/acquisition}/synthetic.py

@@ -5,7 +5,7 @@ the unified Source protocol. SyntheticSource makes synthetic signals consistent
 with all other acquisition methods (files, hardware).
 
 Example:
-    >>> from oscura.acquisition import SyntheticSource
+    >>> from oscura.hardware.acquisition import SyntheticSource
     >>> from oscura import SignalBuilder
     >>>
     >>> # Create signal builder
@@ -41,8 +41,8 @@ from collections.abc import Iterator
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from oscura.builders.signal_builder import SignalBuilder
     from oscura.core.types import Trace, WaveformTrace
+    from oscura.utils.builders.signal_builder import SignalBuilder
 
 
 class SyntheticSource:
@@ -57,7 +57,7 @@ class SyntheticSource:
 
     Example:
         >>> from oscura import SignalBuilder
-        >>> from oscura.acquisition import SyntheticSource
+        >>> from oscura.hardware.acquisition import SyntheticSource
         >>>
         >>> # Create builder
         >>> builder = (SignalBuilder(sample_rate=1e6, duration=0.01)