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

oscura/{exploratory → jupyter/exploratory}/unknown.py

@@ -10,7 +10,7 @@ and protocols, including binary field detection and pattern analysis.
 - UNKNOWN-005: Reverse Engineering Workflow
 
 Example:
-    >>> from oscura.exploratory.unknown import characterize_unknown_signal
+    >>> from oscura.jupyter.exploratory.unknown import characterize_unknown_signal
     >>> result = characterize_unknown_signal(trace)
     >>> print(f"Signal type: {result.signal_type}")
     >>> print(f"Suggested protocols: {result.suggested_protocols}")
@@ -75,35 +75,66 @@ def detect_binary_fields(
     References:
         UNKNOWN-001: Binary Field Detection
     """
+    # Convert analog to digital
+    digital, sample_rate = _convert_to_digital(trace)
+
+    # Find edges and estimate bit period
+    edges = np.where(np.diff(digital) != 0)[0]
+    if len(edges) < 2:
+        return _create_empty_field_result()
+
+    bit_period = np.median(np.diff(edges))
+
+    # Extract fields from edges
+    fields = _extract_binary_fields(
+        edges, digital, bit_period, max_gap_ratio, min_field_bits, sample_rate
+    )
+
+    # Calculate bit rate
+    bit_rate = sample_rate / bit_period if bit_period > 0 else None
+
+    # Detect encoding
+    encoding = _detect_encoding(digital, edges, bit_period)
+
+    # Calculate confidence
+    confidence = min(1.0, len(fields) / 10.0) * 0.8 + (0.2 if bit_rate else 0)
+
+    return BinaryFieldResult(
+        fields=fields,
+        field_count=len(fields),
+        bit_rate=bit_rate,
+        encoding=encoding,
+        confidence=confidence,
+    )
+
+
+def _convert_to_digital(trace: WaveformTrace) -> tuple[NDArray[np.int_], float]:
+    """Convert analog signal to digital representation."""
     data = trace.data
     sample_rate = trace.metadata.sample_rate
-
-    # Threshold for digital conversion
     v_min = np.percentile(data, 5)
     v_max = np.percentile(data, 95)
     threshold = (v_min + v_max) / 2
-
-    # Convert to digital
     digital = (data > threshold).astype(int)
+    return digital, sample_rate
 
-    # Find edges
-    edges = np.where(np.diff(digital) != 0)[0]
 
-    if len(edges) < 2:
-        return BinaryFieldResult(
-            fields=[],
-            field_count=0,
-            bit_rate=None,
-            encoding="unknown",
-            confidence=0.0,
-        )
+def _create_empty_field_result() -> BinaryFieldResult:
+    """Create empty result for insufficient edges."""
+    return BinaryFieldResult(
+        fields=[], field_count=0, bit_rate=None, encoding="unknown", confidence=0.0
+    )
 
-    # Estimate bit period from edge spacing
-    edge_gaps = np.diff(edges)
-    median_gap = np.median(edge_gaps)
-    bit_period = median_gap
 
-    # Group edges into fields
+def _extract_binary_fields(
+    edges: NDArray[np.int_],
+    digital: NDArray[np.int_],
+    bit_period: float,
+    max_gap_ratio: float,
+    min_field_bits: int,
+    sample_rate: float,
+) -> list[dict[str, Any]]:
+    """Extract binary fields from edges."""
     fields = []
     current_field_start = edges[0]
     current_field_edges = [edges[0]]
@@ -114,26 +145,10 @@ def detect_binary_fields(
         if gap > max_gap_ratio * bit_period:
             # End current field
             if len(current_field_edges) >= min_field_bits:
-                current_field_edges[-1] - current_field_edges[0]
-                n_bits = len(current_field_edges) - 1
-
-                # Extract bit pattern
-                bits = []
-                for j in range(len(current_field_edges) - 1):
-                    start = current_field_edges[j]
-                    end = current_field_edges[j + 1]
-                    mid = (start + end) // 2
-                    bits.append(digital[mid])
-
-                fields.append(
-                    {
-                        "start_sample": int(current_field_start),
-                        "end_sample": int(current_field_edges[-1]),
-                        "length": n_bits,
-                        "bits": bits,
-                        "timestamp": current_field_start / sample_rate,
-                    }
+                field = _create_field_from_edges(
+                    current_field_start, current_field_edges, digital, sample_rate
                 )
+                fields.append(field)
 
             # Start new field
             current_field_start = edges[i]
@@ -143,43 +158,36 @@ def detect_binary_fields(
 
     # Handle last field
     if len(current_field_edges) >= min_field_bits:
-        current_field_edges[-1] - current_field_edges[0]
-        n_bits = len(current_field_edges) - 1
-        bits = []
-        for j in range(len(current_field_edges) - 1):
-            start = current_field_edges[j]
-            end = current_field_edges[j + 1]
-            mid = (start + end) // 2
-            bits.append(digital[mid])
-
-        fields.append(
-            {
-                "start_sample": int(current_field_start),
-                "end_sample": int(current_field_edges[-1]),
-                "length": n_bits,
-                "bits": bits,
-                "timestamp": current_field_start / sample_rate,
-            }
+        field = _create_field_from_edges(
+            current_field_start, current_field_edges, digital, sample_rate
         )
+        fields.append(field)
 
-    # Estimate bit rate
-    bit_rate = sample_rate / bit_period if bit_period > 0 else None
-
-    # Detect encoding
-    encoding = _detect_encoding(digital, edges, bit_period)
+    return fields
 
-    # Calculate confidence
-    confidence = min(1.0, len(fields) / 10.0) * 0.8
-    if bit_rate is not None:
-        confidence += 0.2
 
-    return BinaryFieldResult(
-        fields=fields,
-        field_count=len(fields),
-        bit_rate=bit_rate,
-        encoding=encoding,
-        confidence=confidence,
-    )
+def _create_field_from_edges(
+    field_start: int,
+    field_edges: list[int],
+    digital: NDArray[np.int_],
+    sample_rate: float,
+) -> dict[str, Any]:
+    """Create field dictionary from edge list."""
+    n_bits = len(field_edges) - 1
+    bits = []
+    for j in range(len(field_edges) - 1):
+        start = field_edges[j]
+        end = field_edges[j + 1]
+        mid = (start + end) // 2
+        bits.append(digital[mid])
+
+    return {
+        "start_sample": int(field_start),
+        "end_sample": int(field_edges[-1]),
+        "length": n_bits,
+        "bits": bits,
+        "timestamp": field_start / sample_rate,
+    }
 
 
 def _detect_encoding(
@@ -253,156 +261,216 @@ class UnknownSignalCharacterization:
     features: dict[str, Any] = field(default_factory=dict)
 
 
-def characterize_unknown_signal(
-    trace: WaveformTrace,
-) -> UnknownSignalCharacterization:
-    """Comprehensive characterization of unknown signal per UNKNOWN-003.
-
-    Analyzes signal characteristics to determine type, periodicity,
-    and suggest possible protocols.
+def _handle_short_trace(data: NDArray[np.float64]) -> UnknownSignalCharacterization:
+    """Handle edge case of very short traces.
 
     Args:
-        trace: Signal trace to characterize.
+        data: Signal data array
 
     Returns:
-        UnknownSignalCharacterization with all extracted features.
+        UnknownSignalCharacterization with minimal info
+    """
+    return UnknownSignalCharacterization(
+        signal_type="analog",
+        is_periodic=False,
+        fundamental_frequency=None,
+        dc_offset=float(data[0]) if len(data) > 0 else 0.0,
+        amplitude=0.0,
+        rise_time=None,
+        fall_time=None,
+        suggested_protocols=[],
+        noise_floor=0.0,
+        snr_db=float("inf"),
+        features={},
+    )
 
-    Example:
-        >>> result = characterize_unknown_signal(trace)
-        >>> print(f"Signal type: {result.signal_type}")
-        >>> print(f"Periodic: {result.is_periodic}")
-        >>> for protocol, confidence in result.suggested_protocols:
-        ...     print(f"  {protocol}: {confidence:.1%}")
 
-    References:
-        UNKNOWN-003: Unknown Signal Characterization
+def _compute_basic_statistics(
+    data: NDArray[np.float64],
+) -> tuple[float, float, float, float, float, float]:
+    """Compute basic signal statistics.
+
+    Args:
+        data: Signal data array
+
+    Returns:
+        Tuple of (v_min, v_max, v_mean, v_std, dc_offset, amplitude)
     """
-    data = trace.data
-    sample_rate = trace.metadata.sample_rate
+    v_min: float = float(np.min(data))
+    v_max: float = float(np.max(data))
+    v_mean: float = float(np.mean(data))
+    v_std: float = float(np.std(data))
+    dc_offset: float = v_mean
+    amplitude: float = (v_max - v_min) / 2
+    return v_min, v_max, v_mean, v_std, dc_offset, amplitude
 
-    # Handle edge case of very short traces
-    if len(data) < 2:
-        return UnknownSignalCharacterization(
-            signal_type="analog",
-            is_periodic=False,
-            fundamental_frequency=None,
-            dc_offset=float(data[0]) if len(data) > 0 else 0.0,
-            amplitude=0.0,
-            rise_time=None,
-            fall_time=None,
-            suggested_protocols=[],
-            noise_floor=0.0,
-            snr_db=float("inf"),
-            features={},
-        )
 
-    # Basic statistics
-    v_min = np.min(data)
-    v_max = np.max(data)
-    v_mean = np.mean(data)
-    v_std = np.std(data)
+def _find_histogram_peaks(
+    data: NDArray[np.float64],
+    v_min: float,
+    v_max: float,
+) -> list[tuple[float, float]]:
+    """Find peaks in signal histogram for distribution analysis.
 
-    dc_offset = v_mean
-    amplitude = (v_max - v_min) / 2
+    Args:
+        data: Signal data array
+        v_min: Minimum voltage
+        v_max: Maximum voltage
 
-    # Determine signal type
-    # Digital signals have bimodal distribution
+    Returns:
+        List of (peak_position, peak_height) tuples
+    """
     hist, bin_edges = np.histogram(data, bins=50)
     centers = (bin_edges[:-1] + bin_edges[1:]) / 2
 
-    # Find peaks in histogram
     peaks = []
     for i in range(1, len(hist) - 1):
         if hist[i] > hist[i - 1] and hist[i] > hist[i + 1] and hist[i] > 0.1 * np.max(hist):
             peaks.append((centers[i], hist[i]))
 
+    return peaks
+
+
+def _classify_signal_type(
+    peaks: list[tuple[float, float]],
+    v_min: float,
+    v_max: float,
+    v_std: float,
+    amplitude: float,
+) -> Literal["digital", "analog", "mixed"]:
+    """Classify signal type based on histogram peaks.
+
+    Args:
+        peaks: List of histogram peaks
+        v_min: Minimum voltage
+        v_max: Maximum voltage
+        v_std: Standard deviation
+        amplitude: Signal amplitude
+
+    Returns:
+        Signal type classification
+    """
     if len(peaks) >= 4:
-        # Many peaks suggest analog signal (e.g., sine wave with noisy histogram)
-        signal_type: Literal["digital", "analog", "mixed"] = "analog"
+        # Many peaks suggest analog signal
+        return "analog"
     elif len(peaks) == 2 or len(peaks) == 3:
-        # Two peaks suggest digital (bimodal), but check if they're well-separated
+        # Check if peaks are well-separated (digital bimodal)
         peak_positions = [p[0] for p in peaks]
-        # Normalize peak positions to 0-1 range
         normalized_peaks = [(p - v_min) / (v_max - v_min) for p in peak_positions]
 
-        # If peaks are well-separated (one < 0.4, one > 0.6), likely digital
         has_low_peak = any(p < 0.4 for p in normalized_peaks)
         has_high_peak = any(p > 0.6 for p in normalized_peaks)
 
         if has_low_peak and has_high_peak:
-            signal_type = "digital"
+            return "digital"
         else:
-            # Peaks not well separated, likely analog
-            signal_type = "analog"
+            return "analog"
     elif len(peaks) == 1:
         # Check for modulated signal
-        signal_type = "mixed" if v_std > 0.2 * amplitude else "analog"
+        return "mixed" if v_std > 0.2 * amplitude else "analog"
     else:
-        signal_type = "analog"
+        return "analog"
+
+
+def _analyze_periodicity(
+    data: NDArray[np.float64],
+    sample_rate: float,
+) -> tuple[bool, float | None, float, float]:
+    """Analyze signal periodicity using FFT.
 
-    # Check periodicity via FFT
+    Args:
+        data: Signal data array
+        sample_rate: Sample rate in Hz
+
+    Returns:
+        Tuple of (is_periodic, fundamental_frequency, noise_floor, snr_db)
+    """
     from scipy import signal as sp_signal
 
     n = len(data)
-    # Need at least 4 samples for meaningful FFT analysis
-    if n >= 4:
-        f, psd = sp_signal.welch(data, fs=sample_rate, nperseg=min(4096, n))
-
-        # Find dominant frequency (excluding DC)
-        psd_no_dc = psd.copy()
-        psd_no_dc[0] = 0
-
-        if len(psd_no_dc) > 0 and np.any(psd_no_dc > 0):
-            peak_idx = np.argmax(psd_no_dc)
-            mean_psd = np.mean(psd_no_dc[psd_no_dc > 0]) if np.any(psd_no_dc > 0) else 0
-            fundamental_frequency = f[peak_idx] if psd_no_dc[peak_idx] > 10 * mean_psd else None
-        else:
-            fundamental_frequency = None
+    if n < 4:
+        return False, None, 0.0, 0.0
 
-        is_periodic = fundamental_frequency is not None
+    f, psd = sp_signal.welch(data, fs=sample_rate, nperseg=min(4096, n))
+
+    # Find dominant frequency (excluding DC)
+    psd_no_dc = psd.copy()
+    psd_no_dc[0] = 0
+
+    if len(psd_no_dc) > 0 and np.any(psd_no_dc > 0):
+        peak_idx = np.argmax(psd_no_dc)
+        mean_psd = np.mean(psd_no_dc[psd_no_dc > 0]) if np.any(psd_no_dc > 0) else 0
+        fundamental_frequency = f[peak_idx] if psd_no_dc[peak_idx] > 10 * mean_psd else None
     else:
         fundamental_frequency = None
-        is_periodic = False
+
+    is_periodic = fundamental_frequency is not None
 
     # Estimate noise floor
-    if n >= 4:
-        noise_floor = np.median(np.sort(psd)[: len(psd) // 4]) if len(psd) > 0 else 0.0
-        signal_power = np.max(psd) - noise_floor if len(psd) > 0 else 0.0
-    else:
-        noise_floor = 0.0
-        signal_power = 0.0
+    noise_floor = np.median(np.sort(psd)[: len(psd) // 4]) if len(psd) > 0 else 0.0
+    signal_power = np.max(psd) - noise_floor if len(psd) > 0 else 0.0
     snr_db = 10 * np.log10(signal_power / noise_floor) if noise_floor > 0 else 0
 
-    # Estimate rise/fall times for digital signals
-    rise_time = None
-    fall_time = None
+    return is_periodic, fundamental_frequency, noise_floor, snr_db
 
-    if signal_type == "digital":
-        threshold_low = v_min + 0.1 * (v_max - v_min)
-        threshold_high = v_min + 0.9 * (v_max - v_min)
-
-        # Find rising edges
-        rising_times = []
-        falling_times = []
-
-        for i in range(1, len(data) - 1):
-            if data[i - 1] < threshold_low and data[i + 1] > threshold_high:
-                # Rising edge
-                rising_times.append(1 / sample_rate)
-            elif data[i - 1] > threshold_high and data[i + 1] < threshold_low:
-                # Falling edge
-                falling_times.append(1 / sample_rate)
-
-        if rising_times:
-            rise_time = float(np.median(rising_times))
-        if falling_times:
-            fall_time = float(np.median(falling_times))
 
-    # Suggest protocols
-    suggested_protocols = _suggest_protocols(signal_type, fundamental_frequency, sample_rate, data)
+def _estimate_rise_fall_times(
+    data: NDArray[np.float64],
+    v_min: float,
+    v_max: float,
+    sample_rate: float,
+) -> tuple[float | None, float | None]:
+    """Estimate rise and fall times for digital signals.
+
+    Args:
+        data: Signal data array
+        v_min: Minimum voltage
+        v_max: Maximum voltage
+        sample_rate: Sample rate in Hz
+
+    Returns:
+        Tuple of (rise_time, fall_time) in seconds
+    """
+    threshold_low = v_min + 0.1 * (v_max - v_min)
+    threshold_high = v_min + 0.9 * (v_max - v_min)
+
+    rising_times = []
+    falling_times = []
 
-    # Collect features
-    features = {
+    for i in range(1, len(data) - 1):
+        if data[i - 1] < threshold_low and data[i + 1] > threshold_high:
+            rising_times.append(1 / sample_rate)
+        elif data[i - 1] > threshold_high and data[i + 1] < threshold_low:
+            falling_times.append(1 / sample_rate)
+
+    rise_time = float(np.median(rising_times)) if rising_times else None
+    fall_time = float(np.median(falling_times)) if falling_times else None
+
+    return rise_time, fall_time
+
+
+def _build_features_dict(
+    v_min: float,
+    v_max: float,
+    v_mean: float,
+    v_std: float,
+    data: NDArray[np.float64],
+    peaks: list[tuple[float, float]],
+) -> dict[str, Any]:
+    """Build features dictionary for characterization.
+
+    Args:
+        v_min: Minimum voltage
+        v_max: Maximum voltage
+        v_mean: Mean voltage
+        v_std: Standard deviation
+        data: Signal data array
+        peaks: Histogram peaks
+
+    Returns:
+        Dictionary of extracted features
+    """
+    return {
         "v_min": v_min,
         "v_max": v_max,
         "v_mean": v_mean,
@@ -412,6 +480,61 @@ def characterize_unknown_signal(
         "peak_positions": [p[0] for p in peaks],
     }
 
+
+def characterize_unknown_signal(
+    trace: WaveformTrace,
+) -> UnknownSignalCharacterization:
+    """Comprehensive characterization of unknown signal per UNKNOWN-003.
+
+    Analyzes signal characteristics to determine type, periodicity,
+    and suggest possible protocols.
+
+    Args:
+        trace: Signal trace to characterize.
+
+    Returns:
+        UnknownSignalCharacterization with all extracted features.
+
+    Example:
+        >>> result = characterize_unknown_signal(trace)
+        >>> print(f"Signal type: {result.signal_type}")
+        >>> print(f"Periodic: {result.is_periodic}")
+        >>> for protocol, confidence in result.suggested_protocols:
+        ...     print(f"  {protocol}: {confidence:.1%}")
+
+    References:
+        UNKNOWN-003: Unknown Signal Characterization
+    """
+    data = trace.data
+    sample_rate = trace.metadata.sample_rate
+
+    # Handle edge case of very short traces
+    if len(data) < 2:
+        return _handle_short_trace(data)
+
+    # Compute basic statistics
+    v_min, v_max, v_mean, v_std, dc_offset, amplitude = _compute_basic_statistics(data)
+
+    # Find histogram peaks and classify signal type
+    peaks = _find_histogram_peaks(data, v_min, v_max)
+    signal_type = _classify_signal_type(peaks, v_min, v_max, v_std, amplitude)
+
+    # Analyze periodicity
+    is_periodic, fundamental_frequency, noise_floor, snr_db = _analyze_periodicity(
+        data, sample_rate
+    )
+
+    # Estimate rise/fall times for digital signals
+    rise_time, fall_time = None, None
+    if signal_type == "digital":
+        rise_time, fall_time = _estimate_rise_fall_times(data, v_min, v_max, sample_rate)
+
+    # Suggest protocols
+    suggested_protocols = _suggest_protocols(signal_type, fundamental_frequency, sample_rate, data)
+
+    # Build features dictionary
+    features = _build_features_dict(v_min, v_max, v_mean, v_std, data, peaks)
+
     return UnknownSignalCharacterization(
         signal_type=signal_type,
         is_periodic=is_periodic,

oscura/jupyter/magic.py

@@ -68,7 +68,7 @@ except ImportError:
     class Magics:  # type: ignore[no-redef]
         """Fallback Magics class when IPython not available."""
 
-    def magics_class(cls: type[Any]) -> type[Any]:  # type: ignore[no-redef,misc]
+    def magics_class(cls: Any) -> Any:
         """Dummy decorator when IPython not available."""
         return cls
 
@@ -82,14 +82,14 @@ except ImportError:
 
 
 @magics_class
-class OscuraMagics(Magics):  # type: ignore[misc]
+class OscuraMagics(Magics):
     """IPython magics for Oscura analysis.
 
     Provides convenient shortcuts for loading traces, running measurements,
     and displaying results in Jupyter notebooks.
     """
 
-    @line_magic  # type: ignore[misc, untyped-decorator]
+    @line_magic  # type: ignore[untyped-decorator]
     def oscura(self, line: str) -> Any:
         """Oscura line magic for quick operations.
 
@@ -263,7 +263,7 @@ Example:
 """
         print(help_text)
 
-    @cell_magic  # type: ignore[misc, untyped-decorator]
+    @cell_magic  # type: ignore[untyped-decorator]
     def analyze(self, line: str, cell: str) -> Any:
         """Cell magic for multi-line analysis.
 

oscura/{ui → jupyter/ui}/__init__.py

@@ -3,7 +3,7 @@
 Provides user interface patterns for progressive disclosure and formatting utilities.
 """
 
-from oscura.ui.formatters import (
+from oscura.jupyter.ui.formatters import (
     Color,
     FormattedText,
     TextAlignment,
@@ -20,7 +20,7 @@ from oscura.ui.formatters import (
     format_text,
     truncate,
 )
-from oscura.ui.progressive_display import (
+from oscura.jupyter.ui.progressive_display import (
     ProgressiveDisplay,
     ProgressiveOutput,
     Section,

oscura/{ui → jupyter/ui}/formatters.py

@@ -6,7 +6,7 @@ including text alignment, truncation, color codes, and structured output.
 - UI formatting for terminal and web outputs
 
 Example:
-    >>> from oscura.ui.formatters import format_text, truncate, colorize
+    >>> from oscura.jupyter.ui.formatters import format_text, truncate, colorize
     >>> format_text("Status", "active", align="left", width=20)
     '  Status: active'
     >>> truncate("Very long text here", max_length=10)
@@ -294,7 +294,7 @@ def format_status(
         "pass": "✓",
         "fail": "✗",
         "warning": "⚠",
-        "info": "ℹ",  # noqa: RUF001 - intentional unicode info symbol
+        "info": "ℹ",
         "pending": "⏳",
     }
 
@@ -307,7 +307,7 @@ def format_status(
     }
 
     # Get color with default, cast needed because dict.get default is str
-    status_color: ColorName = colors.get(status, "white")  # type: ignore[assignment]
+    status_color: ColorName = colors.get(status, "white")
 
     if use_symbols:
         symbol = symbols.get(status, "•")