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

oscura/discovery/quality_validator.py

@@ -94,98 +94,122 @@ class DataQuality:
     improvement_suggestions: list[dict[str, str]] = field(default_factory=list)
 
 
-def assess_data_quality(
+def _extract_trace_data(
     trace: WaveformTrace | DigitalTrace,
-    *,
-    scenario: AnalysisScenario = "general",
-    protocol_params: dict[str, Any] | None = None,
-    strict_mode: bool = False,
-) -> DataQuality:
-    """Assess whether captured data is adequate for analysis.
-
-    Evaluates sample rate, resolution, duration, and noise level against
-    scenario-specific requirements.
+) -> tuple[NDArray[np.floating[Any]], float, bool]:
+    """Extract data array, sample rate, and type from trace.
 
     Args:
-        trace: Input waveform or digital trace.
-        scenario: Analysis scenario for scenario-specific thresholds.
-        protocol_params: Protocol-specific parameters (e.g., clock frequency).
-        strict_mode: If True, fail on any warnings.
+        trace: Input trace.
 
     Returns:
-        DataQuality assessment with overall status and individual metrics.
+        Tuple of (data, sample_rate, is_analog).
 
     Raises:
-        ValueError: If trace is empty or invalid.
-
-    Example:
-        >>> quality = assess_data_quality(trace, scenario='protocol_decode')
-        >>> print(f"Overall: {quality.status} (confidence: {quality.confidence:.2f})")
-        >>> for metric in quality.metrics:
-        ...     if metric.status != 'PASS':
-        ...         print(f"Issue: {metric.name} - {metric.explanation}")
-        ...         print(f"Fix: {metric.recommendation}")
-
-    References:
-        DISC-009: Data Quality Assessment
+        ValueError: If trace is empty.
     """
-    # Validate input
     if len(trace) == 0:
         raise ValueError("Cannot assess quality of empty trace")
 
-    # Get signal data
     if isinstance(trace, WaveformTrace):
-        data = trace.data
-        sample_rate = trace.metadata.sample_rate
-        is_analog = True
+        return trace.data, trace.metadata.sample_rate, True
     else:
-        data = trace.data.astype(np.float64)
-        sample_rate = trace.metadata.sample_rate
-        is_analog = False
+        return trace.data.astype(np.float64), trace.metadata.sample_rate, False
+
 
-    # Compute basic statistics
+def _prepare_quality_assessment(
+    data: NDArray[np.floating[Any]], protocol_params: dict[str, Any] | None
+) -> tuple[dict[str, float], float, dict[str, Any]]:
+    """Prepare data for quality assessment.
+
+    Args:
+        data: Signal data array.
+        protocol_params: Optional protocol parameters.
+
+    Returns:
+        Tuple of (stats, voltage_swing, protocol_params).
+    """
     stats = basic_stats(data)
     voltage_swing = stats["max"] - stats["min"]
+    return stats, voltage_swing, protocol_params or {}
+
 
-    # Protocol parameters
-    if protocol_params is None:
-        protocol_params = {}
+def _assess_all_quality_metrics(
+    data: NDArray[np.floating[Any]],
+    sample_rate: float,
+    voltage_swing: float,
+    stats: dict[str, float],
+    is_analog: bool,
+    scenario: AnalysisScenario,
+    protocol_params: dict[str, Any],
+) -> list[QualityMetric]:
+    """Assess all quality metrics.
 
-    # Assess individual metrics
-    metrics: list[QualityMetric] = []
+    Args:
+        data: Signal data array.
+        sample_rate: Sample rate in Hz.
+        voltage_swing: Peak-to-peak voltage.
+        stats: Basic statistics.
+        is_analog: Whether signal is analog.
+        scenario: Analysis scenario.
+        protocol_params: Protocol parameters.
 
-    # 1. Sample Rate Assessment
-    sample_rate_metric = _assess_sample_rate(sample_rate, data, stats, scenario, protocol_params)
-    metrics.append(sample_rate_metric)
+    Returns:
+        List of quality metrics.
+    """
+    return [
+        _assess_sample_rate(sample_rate, data, stats, scenario, protocol_params),
+        _assess_resolution(data, voltage_swing, stats, is_analog, scenario),
+        _assess_duration(len(data), sample_rate, data, scenario, protocol_params),
+        _assess_noise(data, voltage_swing, stats, scenario),
+    ]
 
-    # 2. Resolution Assessment
-    resolution_metric = _assess_resolution(data, voltage_swing, stats, is_analog, scenario)
-    metrics.append(resolution_metric)
 
-    # 3. Duration Assessment
-    duration_metric = _assess_duration(len(data), sample_rate, data, scenario, protocol_params)
-    metrics.append(duration_metric)
+def _determine_overall_quality_status(
+    metrics: list[QualityMetric], strict_mode: bool
+) -> QualityStatus:
+    """Determine overall quality status from individual metrics.
 
-    # 4. Noise Level Assessment
-    noise_metric = _assess_noise(data, voltage_swing, stats, scenario)
-    metrics.append(noise_metric)
+    Args:
+        metrics: List of quality metrics.
+        strict_mode: Whether to fail on warnings.
 
-    # Determine overall status
-    failed_metrics = [m for m in metrics if m.status == "FAIL"]
-    warning_metrics = [m for m in metrics if m.status == "WARNING"]
+    Returns:
+        Overall quality status.
+    """
+    failed = [m for m in metrics if m.status == "FAIL"]
+    warnings = [m for m in metrics if m.status == "WARNING"]
 
-    if failed_metrics or (strict_mode and warning_metrics):
-        overall_status: QualityStatus = "FAIL"
-    elif warning_metrics:
-        overall_status = "WARNING"
+    if failed or (strict_mode and warnings):
+        return "FAIL"
+    elif warnings:
+        return "WARNING"
     else:
-        overall_status = "PASS"
+        return "PASS"
+
+
+def _calculate_quality_confidence(metrics: list[QualityMetric]) -> float:
+    """Calculate quality confidence score.
 
-    # Calculate confidence (higher when more metrics pass)
+    Args:
+        metrics: List of quality metrics.
+
+    Returns:
+        Confidence score (0.5-1.0).
+    """
     passed_count = sum(1 for m in metrics if m.passed)
-    confidence = round(0.5 + (passed_count / len(metrics)) * 0.5, 2)
+    return round(0.5 + (passed_count / len(metrics)) * 0.5, 2)
+
+
+def _generate_improvement_suggestions(metrics: list[QualityMetric]) -> list[dict[str, str]]:
+    """Generate improvement suggestions from failed metrics.
+
+    Args:
+        metrics: List of quality metrics.
 
-    # Generate improvement suggestions
+    Returns:
+        List of suggestion dictionaries.
+    """
     suggestions = []
     for metric in metrics:
         if not metric.passed and metric.recommendation:
@@ -198,6 +222,57 @@ def assess_data_quality(
                     else "Medium",
                 }
             )
+    return suggestions
+
+
+def assess_data_quality(
+    trace: WaveformTrace | DigitalTrace,
+    *,
+    scenario: AnalysisScenario = "general",
+    protocol_params: dict[str, Any] | None = None,
+    strict_mode: bool = False,
+) -> DataQuality:
+    """Assess whether captured data is adequate for analysis.
+
+    Evaluates sample rate, resolution, duration, and noise level against
+    scenario-specific requirements.
+
+    Args:
+        trace: Input waveform or digital trace.
+        scenario: Analysis scenario for scenario-specific thresholds.
+        protocol_params: Protocol-specific parameters (e.g., clock frequency).
+        strict_mode: If True, fail on any warnings.
+
+    Returns:
+        DataQuality assessment with overall status and individual metrics.
+
+    Raises:
+        ValueError: If trace is empty or invalid.
+
+    Example:
+        >>> quality = assess_data_quality(trace, scenario='protocol_decode')
+        >>> print(f"Overall: {quality.status} (confidence: {quality.confidence:.2f})")
+        >>> for metric in quality.metrics:
+        ...     if metric.status != 'PASS':
+        ...         print(f"Issue: {metric.name} - {metric.explanation}")
+        ...         print(f"Fix: {metric.recommendation}")
+
+    References:
+        DISC-009: Data Quality Assessment
+    """
+    # Setup: extract and prepare signal data
+    data, sample_rate, is_analog = _extract_trace_data(trace)
+    stats, voltage_swing, protocol_params = _prepare_quality_assessment(data, protocol_params)
+
+    # Processing: assess individual metrics
+    metrics = _assess_all_quality_metrics(
+        data, sample_rate, voltage_swing, stats, is_analog, scenario, protocol_params
+    )
+
+    # Formatting: determine overall status and generate report
+    overall_status = _determine_overall_quality_status(metrics, strict_mode)
+    confidence = _calculate_quality_confidence(metrics)
+    suggestions = _generate_improvement_suggestions(metrics)
 
     return DataQuality(
         status=overall_status,
@@ -272,7 +347,10 @@ def _assess_sample_rate(
         status = "WARNING"
         passed = False
         explanation = f"Sample rate is {abs(margin_percent):.0f}% below recommended"
-        recommendation = f"Increase sample rate to {required_rate / 1e6:.0f} MS/s (currently {sample_rate / 1e6:.0f} MS/s)"
+        recommendation = (
+            f"Increase sample rate to {required_rate / 1e6:.0f} MS/s "
+            f"(currently {sample_rate / 1e6:.0f} MS/s)"
+        )
     else:
         status = "FAIL"
         passed = False
@@ -423,8 +501,14 @@ def _assess_duration(
     elif num_periods >= required_periods * 0.5:
         status = "WARNING"
         passed = False
-        explanation = f"Captured only {num_periods:.0f} signal periods, recommended minimum is {required_periods}"
-        recommendation = f"Increase capture duration to at least {required_duration * 1e3:.1f} ms (currently {duration_sec * 1e3:.1f} ms)"
+        explanation = (
+            f"Captured only {num_periods:.0f} signal periods, "
+            f"recommended minimum is {required_periods}"
+        )
+        recommendation = (
+            f"Increase capture duration to at least {required_duration * 1e3:.1f} ms "
+            f"(currently {duration_sec * 1e3:.1f} ms)"
+        )
     else:
         status = "FAIL"
         passed = False
@@ -496,7 +580,10 @@ def _assess_noise(
     elif noise_percent <= max_noise_percent * 1.5:
         status = "WARNING"
         passed = False
-        explanation = f"Noise level is {noise_percent:.1f}% of signal swing (max recommended: {max_noise_percent:.0f}%)"
+        explanation = (
+            f"Noise level is {noise_percent:.1f}% of signal swing "
+            f"(max recommended: {max_noise_percent:.0f}%)"
+        )
         recommendation = "Reduce noise sources, check grounding, or use averaging"
     else:
         status = "FAIL"

oscura/discovery/signal_detector.py

@@ -98,121 +98,238 @@ def characterize_signal(
     References:
         DISC-001: Automatic Signal Characterization
     """
-    # Validate input
+    # Validate and extract trace data
+    data, sample_rate, is_analog = _validate_and_extract_trace(trace)
+
+    # Compute basic statistics and voltage levels
+    stats = basic_stats(data)
+    voltage_low, voltage_high, voltage_swing = _compute_voltage_levels(data)
+
+    # Run all signal type detectors
+    candidates = _detect_all_signal_types(data, sample_rate, voltage_swing, is_analog)
+
+    # Select best signal type with refinement logic
+    best_type, best_confidence = _select_best_signal_type(candidates)
+
+    # Estimate dominant frequency
+    frequency_hz = _estimate_frequency(data, sample_rate)
+
+    # Extract type-specific parameters and quality metrics
+    parameters = _extract_parameters(best_type, data, sample_rate, voltage_low, voltage_high)
+    quality_metrics = _compute_quality_metrics(
+        data, stats, sample_rate, voltage_low, voltage_high, candidates["digital"]
+    )
+
+    # Prepare alternatives if requested
+    alternatives = _build_alternatives(
+        candidates,
+        best_type,
+        best_confidence,
+        include_alternatives,
+        confidence_threshold,
+        min_alternatives,
+    )
+
+    return SignalCharacterization(
+        signal_type=best_type,
+        confidence=round(best_confidence, 2),
+        voltage_low=voltage_low,
+        voltage_high=voltage_high,
+        frequency_hz=frequency_hz,
+        parameters=parameters,
+        quality_metrics=quality_metrics,
+        alternatives=alternatives,
+    )
+
+
+def _validate_and_extract_trace(
+    trace: WaveformTrace | DigitalTrace,
+) -> tuple[NDArray[np.floating[Any]], float, bool]:
+    """Validate trace and extract data, sample rate, and analog flag.
+
+    Args:
+        trace: Input waveform or digital trace.
+
+    Returns:
+        Tuple of (data, sample_rate, is_analog).
+
+    Raises:
+        ValueError: If trace is empty.
+    """
     if len(trace) == 0:
         raise ValueError("Cannot characterize empty trace")
 
-    # Get signal data
     if isinstance(trace, WaveformTrace):
-        data = trace.data
-        sample_rate = trace.metadata.sample_rate
-        is_analog = True
+        return trace.data, trace.metadata.sample_rate, True
     else:
-        data = trace.data.astype(np.float64)
-        sample_rate = trace.metadata.sample_rate
-        is_analog = False
+        return trace.data.astype(np.float64), trace.metadata.sample_rate, False
 
-    # Compute basic statistics
-    stats = basic_stats(data)
 
-    # Determine voltage levels using percentiles to be robust to noise
-    # Use 5th and 95th percentiles to ignore outliers from noise
+def _compute_voltage_levels(
+    data: NDArray[np.floating[Any]],
+) -> tuple[float, float, float]:
+    """Compute voltage levels using robust percentiles.
+
+    Args:
+        data: Signal data array.
+
+    Returns:
+        Tuple of (voltage_low, voltage_high, voltage_swing).
+    """
     voltage_low = float(np.percentile(data, 5))
     voltage_high = float(np.percentile(data, 95))
     voltage_swing = voltage_high - voltage_low
+    return voltage_low, voltage_high, voltage_swing
 
-    # Analyze signal characteristics
-    candidates: dict[SignalType, float] = {}
 
-    # Check for digital signal (bimodal distribution)
-    digital_confidence = _detect_digital(data, voltage_swing)
-    candidates["digital"] = digital_confidence
+def _detect_all_signal_types(
+    data: NDArray[np.floating[Any]],
+    sample_rate: float,
+    voltage_swing: float,
+    is_analog: bool,
+) -> dict[SignalType, float]:
+    """Run all signal type detectors and return confidence scores.
 
-    # Check for analog signal (continuous distribution)
-    analog_confidence = _detect_analog(data, voltage_swing, is_analog)
-    candidates["analog"] = analog_confidence
+    Args:
+        data: Signal data array.
+        sample_rate: Sample rate in Hz.
+        voltage_swing: Peak-to-peak voltage swing.
+        is_analog: Whether input is from analog trace.
 
-    # Check for PWM (periodic square wave with varying duty cycle)
-    pwm_confidence = _detect_pwm(data, sample_rate, voltage_swing)
-    candidates["pwm"] = pwm_confidence
+    Returns:
+        Dictionary mapping signal types to confidence scores.
+    """
+    return {
+        "digital": _detect_digital(data, voltage_swing),
+        "analog": _detect_analog(data, voltage_swing, is_analog),
+        "pwm": _detect_pwm(data, sample_rate, voltage_swing),
+        "uart": _detect_uart(data, sample_rate, voltage_swing),
+        "spi": _detect_spi(data, sample_rate, voltage_swing),
+        "i2c": _detect_i2c(data, sample_rate, voltage_swing),
+    }
 
-    # Check for UART (asynchronous serial with start/stop bits)
-    uart_confidence = _detect_uart(data, sample_rate, voltage_swing)
-    candidates["uart"] = uart_confidence
 
-    # Check for SPI (synchronous with clock and data)
-    spi_confidence = _detect_spi(data, sample_rate, voltage_swing)
-    candidates["spi"] = spi_confidence
+def _select_best_signal_type(
+    candidates: dict[SignalType, float],
+) -> tuple[SignalType, float]:
+    """Select best signal type with refinement logic.
 
-    # Check for I2C (two-wire with specific patterns)
-    i2c_confidence = _detect_i2c(data, sample_rate, voltage_swing)
-    candidates["i2c"] = i2c_confidence
+    Args:
+        candidates: Dictionary of signal types and confidence scores.
 
-    # Select best match
+    Returns:
+        Tuple of (best_type, best_confidence).
+    """
     sorted_candidates = sorted(candidates.items(), key=lambda x: x[1], reverse=True)
     best_type, best_confidence = sorted_candidates[0]
 
     # If confidence is too low, mark as unknown
     if best_confidence < 0.5:
-        best_type = "unknown"
+        return "unknown", best_confidence
 
-    # If analog won but digital score is meaningful, prefer digital/unknown
-    # This handles noisy digital signals that look analog-ish
+    # Refine analog classification if digital characteristics present
     if best_type == "analog":
-        # Check if any protocol detector had reasonable confidence
-        protocol_confidence = max(
-            candidates.get("uart", 0),
-            candidates.get("spi", 0),
-            candidates.get("pwm", 0),
-        )
-
-        # If digital or protocol detectors have some confidence, don't call it purely analog
-        if digital_confidence > 0.3 or protocol_confidence > 0.2:
-            # Signal has digital characteristics - don't call it analog
-            if protocol_confidence > 0.3:
-                best_type = "unknown"  # Too noisy/ambiguous to classify as specific protocol
-                best_confidence = protocol_confidence
-            elif digital_confidence > 0.4:
-                best_type = "digital"  # Generic digital signal
-                best_confidence = digital_confidence
-            else:
-                best_type = "unknown"  # Too ambiguous
-                best_confidence = max(digital_confidence, protocol_confidence, analog_confidence)
+        return _refine_analog_classification(candidates)
 
-    # Estimate dominant frequency
-    frequency_hz = _estimate_frequency(data, sample_rate)
+    return best_type, best_confidence
 
-    # Extract type-specific parameters
-    parameters = _extract_parameters(best_type, data, sample_rate, voltage_low, voltage_high)
 
-    # Calculate quality metrics with improved noise estimation
+def _refine_analog_classification(
+    candidates: dict[SignalType, float],
+) -> tuple[SignalType, float]:
+    """Refine analog classification when digital characteristics are present.
+
+    Args:
+        candidates: Dictionary of signal types and confidence scores.
+
+    Returns:
+        Tuple of (refined_type, confidence).
+    """
+    digital_confidence = candidates.get("digital", 0)
+    analog_confidence = candidates.get("analog", 0)
+    protocol_confidence = max(
+        candidates.get("uart", 0),
+        candidates.get("spi", 0),
+        candidates.get("pwm", 0),
+    )
+
+    # If digital or protocol detectors have some confidence, don't call it purely analog
+    if digital_confidence > 0.3 or protocol_confidence > 0.2:
+        if protocol_confidence > 0.3:
+            return "unknown", protocol_confidence
+        elif digital_confidence > 0.4:
+            return "digital", digital_confidence
+        else:
+            return "unknown", max(digital_confidence, protocol_confidence, analog_confidence)
+
+    return "analog", analog_confidence
+
+
+def _compute_quality_metrics(
+    data: NDArray[np.floating[Any]],
+    stats: dict[str, float],
+    sample_rate: float,
+    voltage_low: float,
+    voltage_high: float,
+    digital_confidence: float,
+) -> dict[str, float]:
+    """Compute signal quality metrics.
+
+    Args:
+        data: Signal data array.
+        stats: Basic statistics dictionary.
+        sample_rate: Sample rate in Hz.
+        voltage_low: Low voltage level.
+        voltage_high: High voltage level.
+        digital_confidence: Confidence that signal is digital.
+
+    Returns:
+        Dictionary of quality metrics.
+    """
     noise_level = _estimate_noise_level(data, voltage_low, voltage_high, digital_confidence)
-    quality_metrics = {
+    return {
         "snr_db": _estimate_snr(data, stats),
         "jitter_ns": _estimate_jitter(data, sample_rate) * 1e9,
         "noise_level": noise_level,
     }
 
-    # Prepare alternatives
+
+def _build_alternatives(
+    candidates: dict[SignalType, float],
+    best_type: SignalType,
+    best_confidence: float,
+    include_alternatives: bool,
+    confidence_threshold: float,
+    min_alternatives: int,
+) -> list[tuple[SignalType, float]]:
+    """Build list of alternative signal type suggestions.
+
+    Args:
+        candidates: All candidate types with confidence scores.
+        best_type: Best detected signal type.
+        best_confidence: Confidence of best type.
+        include_alternatives: Whether to include alternatives.
+        confidence_threshold: Threshold for including alternatives.
+        min_alternatives: Minimum number of alternatives.
+
+    Returns:
+        List of (signal_type, confidence) tuples.
+    """
     alternatives: list[tuple[SignalType, float]] = []
-    if include_alternatives or best_confidence < confidence_threshold:
-        # Include top alternatives (excluding the winner)
-        for sig_type, conf in sorted_candidates[1:]:
-            if len(alternatives) >= min_alternatives:
-                break
-            if conf >= 0.3:  # Only include reasonable alternatives
-                alternatives.append((sig_type, conf))
 
-    return SignalCharacterization(
-        signal_type=best_type,
-        confidence=round(best_confidence, 2),
-        voltage_low=voltage_low,
-        voltage_high=voltage_high,
-        frequency_hz=frequency_hz,
-        parameters=parameters,
-        quality_metrics=quality_metrics,
-        alternatives=alternatives,
-    )
+    if not (include_alternatives or best_confidence < confidence_threshold):
+        return alternatives
+
+    sorted_candidates = sorted(candidates.items(), key=lambda x: x[1], reverse=True)
+
+    # Include top alternatives (excluding the winner)
+    for sig_type, conf in sorted_candidates[1:]:
+        if len(alternatives) >= min_alternatives:
+            break
+        if conf >= 0.3:  # Only include reasonable alternatives
+            alternatives.append((sig_type, conf))
+
+    return alternatives
 
 
 def _estimate_noise_level(

oscura/export/__init__.py

@@ -5,33 +5,31 @@ to various formats for integration with other tools and workflows.
 
 Supported export formats:
 - Wireshark Lua dissectors
-- (Future) Scapy packet definitions
-- (Future) Kaitai Struct definitions
+- Kaitai Struct definitions (.ksy)
+- Scapy packet layers
 - (Future) C/C++ parser code
 
 Example:
-    >>> from oscura.export.wireshark import WiresharkDissectorGenerator
-    >>> from oscura.inference.protocol_dsl import ProtocolDefinition
-    >>> protocol = ProtocolDefinition(name="myproto", description="My Protocol")
-    >>> generator = WiresharkDissectorGenerator()
-    >>> generator.generate(protocol, Path("myproto.lua"))
+    >>> from oscura.export.wireshark_dissector import WiresharkDissectorGenerator
+    >>> from oscura.export.kaitai_struct import KaitaiStructGenerator
+    >>> from oscura.export.scapy_layer import ScapyLayerGenerator
+    >>> from oscura.workflows.reverse_engineering import ProtocolSpec
+    >>> # Generate Wireshark dissector
+    >>> wireshark_gen = WiresharkDissectorGenerator(config)
+    >>> wireshark_gen.generate(spec, Path("myproto.lua"))
+    >>> # Generate Kaitai Struct definition
+    >>> kaitai_gen = KaitaiStructGenerator(config)
+    >>> kaitai_gen.generate(spec, Path("myproto.ksy"))
+    >>> # Generate Scapy layer
+    >>> scapy_gen = ScapyLayerGenerator(config)
+    >>> scapy_gen.generate(spec, messages, Path("proto_layer.py"))
 """
 
 # Import main exports
-from . import wireshark
-from .wavedrom import (
-    WaveDromBuilder,
-    WaveDromEdge,
-    WaveDromSignal,
-    export_wavedrom,
-    from_digital_trace,
-)
+from . import kaitai_struct, scapy_layer, wireshark
 
 __all__ = [
-    "WaveDromBuilder",
-    "WaveDromEdge",
-    "WaveDromSignal",
-    "export_wavedrom",
-    "from_digital_trace",
+    "kaitai_struct",
+    "scapy_layer",
     "wireshark",
 ]