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

oscura/cli/validate_cmd.py

@@ -0,0 +1,204 @@
+"""Oscura Validate Command - Protocol Specification Validation.
+
+Provides CLI for validating protocol specifications and message structures.
+
+
+Example:
+    $ oscura validate protocol_spec.yaml
+    $ oscura validate --spec uart --test-data capture.wfm
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import click
+
+logger = logging.getLogger("oscura.cli.validate")
+
+
+@click.command()
+@click.argument("spec", type=click.Path(exists=True))
+@click.option(
+    "--test-data",
+    type=click.Path(exists=True),
+    default=None,
+    help="Test data file for validation.",
+)
+@click.option(
+    "--output",
+    type=click.Choice(["json", "table"], case_sensitive=False),
+    default="table",
+    help="Output format.",
+)
+@click.pass_context
+def validate(
+    ctx: click.Context,
+    spec: str,
+    test_data: str | None,
+    output: str,
+) -> None:
+    """Validate protocol specification.
+
+    Validates protocol specification files (YAML/JSON) and optionally
+    tests them against real data.
+
+    Args:
+        ctx: Click context object.
+        spec: Path to specification file.
+        test_data: Optional test data file.
+        output: Output format.
+
+    Examples:
+
+        \b
+        # Validate spec only
+        $ oscura validate protocol_spec.yaml
+
+        \b
+        # Validate against test data
+        $ oscura validate uart_spec.yaml --test-data capture.wfm
+    """
+    verbose = ctx.obj.get("verbose", 0)
+
+    if verbose:
+        logger.info(f"Validating specification: {spec}")
+
+    try:
+        import yaml
+
+        # Load specification
+        spec_path = Path(spec)
+        with open(spec_path) as f:
+            if spec_path.suffix in [".yaml", ".yml"]:
+                spec_data = yaml.safe_load(f)
+            else:
+                import json
+
+                spec_data = json.load(f)
+
+        # Validate spec structure
+        validation_results: dict[str, Any] = {
+            "spec_file": str(spec_path.name),
+            "valid": True,
+            "errors": [],
+            "warnings": [],
+        }
+
+        _validate_spec_structure(spec_data, validation_results)
+
+        # Validate against test data if provided
+        if test_data:
+            from oscura.loaders import load
+
+            trace = load(test_data)
+            _validate_against_data(spec_data, trace, validation_results)
+
+        # Output results
+        if output == "json":
+            import json
+
+            click.echo(json.dumps(validation_results, indent=2))
+        else:
+            _print_validation_results(validation_results)
+
+        # Exit with error if validation failed
+        if not validation_results["valid"]:
+            ctx.exit(1)
+
+    except Exception as e:
+        logger.error(f"Validation failed: {e}")
+        if verbose > 1:
+            raise
+        click.echo(f"Error: {e}", err=True)
+        ctx.exit(1)
+
+
+def _validate_spec_structure(spec: dict[str, Any], results: dict[str, Any]) -> None:
+    """Validate specification structure.
+
+    Args:
+        spec: Specification dictionary.
+        results: Results dictionary to update.
+    """
+    required_fields = ["name", "version"]
+
+    for field in required_fields:
+        if field not in spec:
+            results["errors"].append(f"Missing required field: {field}")
+            results["valid"] = False
+
+    # Check optional but recommended fields
+    recommended_fields = ["description", "fields", "constraints"]
+    for field in recommended_fields:
+        if field not in spec:
+            results["warnings"].append(f"Missing recommended field: {field}")
+
+    # Validate fields if present
+    if "fields" in spec and isinstance(spec["fields"], list):
+        for i, field in enumerate(spec["fields"]):
+            if not isinstance(field, dict):
+                results["errors"].append(f"Field {i} is not a dictionary")
+                results["valid"] = False
+            elif "name" not in field:
+                results["errors"].append(f"Field {i} missing 'name' attribute")
+                results["valid"] = False
+
+
+def _validate_against_data(spec: dict[str, Any], trace: Any, results: dict[str, Any]) -> None:
+    """Validate specification against test data.
+
+    Args:
+        spec: Specification dictionary.
+        trace: Test data trace.
+        results: Results dictionary to update.
+    """
+    # Check sample rate requirements
+    if "sample_rate_min" in spec:
+        min_rate = spec["sample_rate_min"]
+        if trace.metadata.sample_rate < min_rate:
+            results["warnings"].append(
+                f"Sample rate {trace.metadata.sample_rate} below minimum {min_rate}"
+            )
+
+    # Check data length
+    if "min_samples" in spec:
+        min_samples = spec["min_samples"]
+        if len(trace.data) < min_samples:
+            results["errors"].append(
+                f"Data has {len(trace.data)} samples, need at least {min_samples}"
+            )
+            results["valid"] = False
+
+    results["test_data_samples"] = len(trace.data)
+    results["test_data_sample_rate"] = trace.metadata.sample_rate
+
+
+def _print_validation_results(results: dict[str, Any]) -> None:
+    """Print validation results.
+
+    Args:
+        results: Validation results dictionary.
+    """
+    click.echo("\n=== Validation Results ===\n")
+    click.echo(f"Specification: {results['spec_file']}")
+    click.echo(f"Status: {'PASS' if results['valid'] else 'FAIL'}\n")
+
+    if results["errors"]:
+        click.echo("Errors:")
+        for err in results["errors"]:
+            click.echo(f"  - {err}")
+        click.echo()
+
+    if results["warnings"]:
+        click.echo("Warnings:")
+        for warn in results["warnings"]:
+            click.echo(f"  - {warn}")
+        click.echo()
+
+    if "test_data_samples" in results:
+        click.echo("Test Data:")
+        click.echo(f"  Samples: {results['test_data_samples']}")
+        click.echo(f"  Sample Rate: {results['test_data_sample_rate']} Hz")

oscura/cli/visualize.py

@@ -0,0 +1,158 @@
+"""Oscura Visualize Command - Interactive Waveform Viewer.
+
+Provides CLI for launching interactive waveform visualization.
+
+
+Example:
+    $ oscura visualize signal.wfm
+    $ oscura visualize capture.wfm --protocol uart
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+
+    from oscura.core.types import WaveformTrace
+
+logger = logging.getLogger("oscura.cli.visualize")
+
+
+@click.command()
+@click.argument("file", type=click.Path(exists=True))
+@click.option(
+    "--protocol",
+    type=str,
+    default=None,
+    help="Protocol for overlay annotations.",
+)
+@click.option(
+    "--save",
+    type=click.Path(),
+    default=None,
+    help="Save plot to file instead of showing.",
+)
+@click.pass_context
+def visualize(
+    ctx: click.Context,
+    file: str,
+    protocol: str | None,
+    save: str | None,
+) -> None:
+    """Launch interactive waveform viewer.
+
+    Opens an interactive plot window for waveform analysis with zoom,
+    pan, and measurement tools.
+
+    Args:
+        ctx: Click context object.
+        file: Path to waveform file.
+        protocol: Optional protocol for annotations.
+        save: Save plot to file instead of displaying.
+
+    Examples:
+
+        \b
+        # Interactive viewer
+        $ oscura visualize signal.wfm
+
+        \b
+        # With protocol overlay
+        $ oscura visualize capture.wfm --protocol uart
+
+        \b
+        # Save to file
+        $ oscura visualize data.wfm --save plot.png
+    """
+    verbose = ctx.obj.get("verbose", 0)
+
+    if verbose:
+        logger.info(f"Visualizing: {file}")
+
+    try:
+        import matplotlib.pyplot as plt
+        import numpy as np
+
+        from oscura.core.types import IQTrace, WaveformTrace
+        from oscura.loaders import load
+
+        # Load file
+        trace = load(file)
+
+        # Create plot
+        fig, ax = plt.subplots(figsize=(12, 6))
+
+        # Plot waveform (handle IQTrace separately)
+        if isinstance(trace, IQTrace):
+            # Plot I/Q components
+            time_axis = np.arange(len(trace.i_data)) / trace.metadata.sample_rate
+            ax.plot(time_axis * 1e3, trace.i_data, linewidth=0.5, label="I")
+            ax.plot(time_axis * 1e3, trace.q_data, linewidth=0.5, label="Q")
+            ax.legend()
+        else:
+            # Plot regular waveform or digital trace
+            time_axis = np.arange(len(trace.data)) / trace.metadata.sample_rate
+            ax.plot(time_axis * 1e3, trace.data, linewidth=0.5)
+
+        ax.set_xlabel("Time (ms)")
+        ax.set_ylabel("Voltage (V)")
+        ax.set_title(f"Waveform: {Path(file).name}")
+        ax.grid(True, alpha=0.3)
+
+        # Add protocol overlay if requested (only for non-IQ traces)
+        if protocol and isinstance(trace, WaveformTrace):
+            _add_protocol_overlay(ax, trace, protocol)
+
+        # Save or show
+        if save:
+            plt.savefig(save, dpi=300, bbox_inches="tight")
+            click.echo(f"Saved to: {save}")
+        else:
+            plt.tight_layout()
+            plt.show()
+
+    except Exception as e:
+        logger.error(f"Visualization failed: {e}")
+        if verbose > 1:
+            raise
+        click.echo(f"Error: {e}", err=True)
+        ctx.exit(1)
+
+
+def _add_protocol_overlay(ax: Axes, trace: WaveformTrace, protocol: str) -> None:
+    """Add protocol annotations to plot.
+
+    Args:
+        ax: Matplotlib axis.
+        trace: Waveform trace.
+        protocol: Protocol name.
+    """
+    import numpy as np
+
+    # Convert to digital
+    threshold = (np.max(trace.data) + np.min(trace.data)) / 2
+    digital = trace.data > threshold
+
+    # Find edges
+    edges = np.where(np.diff(digital.astype(int)) != 0)[0]
+
+    # Mark edges
+    time_axis = np.arange(len(trace.data)) / trace.metadata.sample_rate
+    for edge in edges[:100]:  # Limit to first 100 edges
+        ax.axvline(time_axis[edge] * 1e3, color="red", alpha=0.3, linewidth=0.5)
+
+    ax.text(
+        0.98,
+        0.98,
+        f"Protocol: {protocol.upper()}",
+        transform=ax.transAxes,
+        ha="right",
+        va="top",
+        bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.5},
+    )

oscura/convenience.py

@@ -195,109 +195,142 @@ def auto_decode(
     References:
         sigrok Protocol Decoder API
     """
+
+    # Prepare digital trace
+    digital_trace = _prepare_digital_trace(trace)
+
+    # Detect or use specified protocol
+    protocol, config, confidence = _detect_or_select_protocol(
+        trace, protocol, min_confidence, digital_trace
+    )
+
+    # Decode frames
+    frames, errors = _decode_protocol_frames(protocol, config, digital_trace)
+
+    # Calculate statistics
+    error_frames = sum(1 for f in frames if hasattr(f, "errors") and f.errors)
+    statistics = {
+        "total_frames": len(frames),
+        "error_frames": error_frames,
+        "error_rate": error_frames / len(frames) if frames else 0,
+    }
+
+    return DecodeResult(
+        protocol=protocol,
+        frames=frames,
+        confidence=confidence,
+        baud_rate=config.get("baud_rate"),
+        config=config,
+        errors=errors,
+        statistics=statistics,
+    )
+
+
+def _prepare_digital_trace(trace: WaveformTrace | DigitalTrace) -> DigitalTrace:
+    """Convert to digital trace if needed."""
     from oscura.core.types import WaveformTrace
-    from oscura.inference.protocol import detect_protocol
 
-    # Convert to digital if needed
     if isinstance(trace, WaveformTrace):
         from oscura.analyzers.digital.extraction import to_digital
 
-        digital_trace = to_digital(trace, threshold="auto")
-    else:
-        digital_trace = trace
+        return to_digital(trace, threshold="auto")
+    return trace
+
+
+def _detect_or_select_protocol(
+    trace: WaveformTrace | DigitalTrace,
+    protocol: str | None,
+    min_confidence: float,
+    digital_trace: DigitalTrace,
+) -> tuple[str, dict[str, Any], float]:
+    """Detect protocol or use specified one."""
+    from oscura.core.types import WaveformTrace
 
-    # Auto-detect protocol if not specified
     if protocol is None or protocol.lower() == "auto":
-        # detect_protocol only accepts WaveformTrace, use original trace if it's waveform
         if isinstance(trace, WaveformTrace):
+            from oscura.inference.protocol import detect_protocol
+
             detection = detect_protocol(
                 trace, min_confidence=min_confidence, return_candidates=True
             )
         else:
-            # For DigitalTrace, we can't auto-detect protocol, use default UART
             detection = {"protocol": "UART", "config": {}, "confidence": 0.5}
-        protocol = detection.get("protocol", "unknown")
-        config = detection.get("config", {})
-        confidence = detection.get("confidence", 0.0)
+        return (
+            detection.get("protocol", "unknown"),
+            detection.get("config", {}),
+            detection.get("confidence", 0.0),
+        )
     else:
-        protocol = protocol.upper()
-        confidence = 1.0
-        config = _get_default_protocol_config(protocol)
+        return protocol.upper(), _get_default_protocol_config(protocol.upper()), 1.0
+
 
-    # Decode based on protocol
+def _decode_protocol_frames(
+    protocol: str, config: dict[str, Any], digital_trace: DigitalTrace
+) -> tuple[list[Any], list[str]]:
+    """Decode frames based on detected protocol."""
     frames: list[Any] = []
     errors: list[str] = []
 
     try:
         if protocol == "UART":
-            from oscura.analyzers.protocols.uart import UARTDecoder
-
-            baud_rate = config.get("baud_rate", 115200)
-            decoder = UARTDecoder(
-                baudrate=baud_rate,
-                data_bits=config.get("data_bits", 8),
-                parity=config.get("parity", "none"),
-                stop_bits=config.get("stop_bits", 1),
-            )
-            frames = list(decoder.decode(digital_trace))
-
+            frames = _decode_uart(digital_trace, config)
         elif protocol == "SPI":
-            from oscura.analyzers.protocols.spi import SPIDecoder
-
-            spi_decoder = SPIDecoder(
-                cpol=config.get("clock_polarity", 0),
-                cpha=config.get("clock_phase", 0),
-            )
-            # Single channel decode - pass trace with channel mapping
-            frames = list(
-                spi_decoder.decode(digital_trace, clk=digital_trace.data, mosi=digital_trace.data)
-            )
-
+            frames = _decode_spi(digital_trace, config)
         elif protocol == "I2C":
-            from oscura.analyzers.protocols.i2c import I2CDecoder
-
-            i2c_decoder = I2CDecoder()
-            # Single channel - use SDA and create synthetic SCL
-            sda = digital_trace.data
-            edges = np.where(np.diff(sda.astype(int)) != 0)[0]
-            scl = np.ones_like(sda, dtype=bool)
-            for i, edge in enumerate(edges):
-                if i % 2 == 0 and edge + 10 < len(scl):
-                    scl[edge : edge + 10] = False
-            frames = list(i2c_decoder.decode(digital_trace, scl=scl, sda=sda))
-
+            frames = _decode_i2c(digital_trace, config)
         elif protocol == "CAN":
-            from oscura.analyzers.protocols.can import CANDecoder
-
-            can_decoder = CANDecoder(
-                bitrate=config.get("baud_rate", 500000),
-                sample_point=config.get("sample_point", 0.75),
-            )
-            frames = list(can_decoder.decode(digital_trace))
-
+            frames = _decode_can(digital_trace, config)
         else:
             errors.append(f"Unsupported protocol: {protocol}")
-
     except Exception as e:
         errors.append(f"Decoding error: {e!s}")
 
-    # Calculate statistics
-    error_frames = sum(1 for f in frames if hasattr(f, "errors") and f.errors)
-    statistics = {
-        "total_frames": len(frames),
-        "error_frames": error_frames,
-        "error_rate": error_frames / len(frames) if frames else 0,
-    }
+    return frames, errors
 
-    return DecodeResult(
-        protocol=protocol,
-        frames=frames,
-        confidence=confidence,
-        baud_rate=config.get("baud_rate"),
-        config=config,
-        errors=errors,
-        statistics=statistics,
+
+def _decode_uart(digital_trace: DigitalTrace, config: dict[str, Any]) -> list[Any]:
+    """Decode UART frames."""
+    from oscura.analyzers.protocols.uart import UARTDecoder
+
+    decoder = UARTDecoder(
+        baudrate=config.get("baud_rate", 115200),
+        data_bits=config.get("data_bits", 8),
+        parity=config.get("parity", "none"),
+        stop_bits=config.get("stop_bits", 1),
+    )
+    return list(decoder.decode(digital_trace))
+
+
+def _decode_spi(digital_trace: DigitalTrace, config: dict[str, Any]) -> list[Any]:
+    """Decode SPI frames."""
+    from oscura.analyzers.protocols.spi import SPIDecoder
+
+    decoder = SPIDecoder(cpol=config.get("clock_polarity", 0), cpha=config.get("clock_phase", 0))
+    return list(decoder.decode(digital_trace, clk=digital_trace.data, mosi=digital_trace.data))
+
+
+def _decode_i2c(digital_trace: DigitalTrace, config: dict[str, Any]) -> list[Any]:
+    """Decode I2C frames."""
+    from oscura.analyzers.protocols.i2c import I2CDecoder
+
+    decoder = I2CDecoder()
+    sda = digital_trace.data
+    edges = np.where(np.diff(sda.astype(int)) != 0)[0]
+    scl = np.ones_like(sda, dtype=bool)
+    for i, edge in enumerate(edges):
+        if i % 2 == 0 and edge + 10 < len(scl):
+            scl[edge : edge + 10] = False
+    return list(decoder.decode(digital_trace, scl=scl, sda=sda))
+
+
+def _decode_can(digital_trace: DigitalTrace, config: dict[str, Any]) -> list[Any]:
+    """Decode CAN frames."""
+    from oscura.analyzers.protocols.can import CANDecoder
+
+    decoder = CANDecoder(
+        bitrate=config.get("baud_rate", 500000), sample_point=config.get("sample_point", 0.75)
     )
+    return list(decoder.decode(digital_trace))
 
 
 def smart_filter(
@@ -330,7 +363,7 @@ def smart_filter(
         >>> # Or auto-detect
         >>> clean = osc.smart_filter(noisy, target="auto")
     """
-    from oscura.filtering.convenience import (
+    from oscura.utils.filtering.convenience import (
         high_pass,
         low_pass,
         median_filter,
@@ -405,11 +438,24 @@ def _detect_noise_type(
     # Get noise floor estimate
     noise_floor = np.median(mag_db[10 : len(mag_db) // 4])
 
-    # Check for power line hum
-    if idx_60 < len(mag_db) and mag_db[idx_60] > noise_floor + 20:
-        return "60hz_hum"
-    if idx_50 < len(mag_db) and mag_db[idx_50] > noise_floor + 20:
-        return "50hz_hum"
+    # Check for power line hum - must be clear peak at exact frequency
+    # Verify it's a local maximum to avoid false positives from spectral leakage
+    if idx_60 < len(mag_db) - 5 and idx_60 > 5 and idx_60 < len(freq):
+        # Must be within 3 Hz of actual 60 Hz (tighter tolerance)
+        if abs(freq[idx_60] - 60) < 3:
+            # Check if it's a local maximum (peak, not leakage)
+            local_max = mag_db[idx_60 - 2 : idx_60 + 3].max()
+            is_peak = mag_db[idx_60] >= local_max - 0.1  # Allow tiny numerical error
+            if is_peak and mag_db[idx_60] > noise_floor + 20:
+                return "60hz_hum"
+    if idx_50 < len(mag_db) - 5 and idx_50 > 5 and idx_50 < len(freq):
+        # Must be within 3 Hz of actual 50 Hz (tighter tolerance)
+        if abs(freq[idx_50] - 50) < 3:
+            # Check if it's a local maximum (peak, not leakage)
+            local_max = mag_db[idx_50 - 2 : idx_50 + 3].max()
+            is_peak = mag_db[idx_50] >= local_max - 0.1  # Allow tiny numerical error
+            if is_peak and mag_db[idx_50] > noise_floor + 20:
+                return "50hz_hum"
 
     # Check frequency distribution
     low_power = np.mean(mag_db[1 : len(mag_db) // 10])

oscura/core/__init__.py

@@ -39,8 +39,9 @@ from oscura.core.cross_domain import (
     correlate_results,
 )
 from oscura.core.debug import (
+    DebugContext,
     DebugLevel,
-    debug_context,
+    debug_context,  # Backward compatibility alias
     disable_debug,
     enable_debug,
     get_debug_level,
@@ -180,6 +181,7 @@ __all__ = [
     "CorrelationResult",
     "CrossDomainCorrelator",
     "CrossDomainInsight",
+    "DebugContext",
     "DebugLevel",
     "DigitalTrace",
     # Edge cases (EDGE-001, EDGE-002, EDGE-003)
@@ -251,7 +253,7 @@ __all__ = [
     "create_progress_tracker",
     "create_provenance",
     "create_simple_progress",
-    "debug_context",
+    "debug_context",  # Backward compatibility
     "disable_debug",
     # Debug (LOG-007)
     "enable_debug",

oscura/core/backend_selector.py

@@ -43,7 +43,7 @@ except (ImportError, AttributeError):
     HAS_GPU = False
 
 try:
-    import numba  # type: ignore[import-not-found]
+    import numba
 
     HAS_NUMBA = True
     del numba
@@ -51,10 +51,10 @@ except ImportError:
     HAS_NUMBA = False
 
 try:
-    import dask.array  # type: ignore[import-not-found, import-untyped]
+    import dask.array  # type: ignore[import-not-found]  # Optional dependency
 
     HAS_DASK = True
-    del dask  # type: ignore[name-defined]
+    del dask
 except ImportError:
     HAS_DASK = False