oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/cli/__init__.py

@@ -0,0 +1,14 @@
+"""TraceKit Command-Line Interface.
+
+This module provides command-line tools for signal analysis workflows.
+
+
+Example:
+    $ oscura --help
+    $ oscura characterize signal.wfm
+    $ oscura decode uart.wfm --protocol uart
+"""
+
+from oscura.cli.main import cli
+
+__all__ = ["cli"]

oscura/cli/batch.py

@@ -0,0 +1,339 @@
+"""TraceKit Batch Command implementing CLI-004.
+
+Provides CLI for batch processing multiple files with parallel execution support.
+
+
+Example:
+    $ oscura batch '*.wfm' --analysis characterize
+    $ oscura batch 'test_*.wfm' --analysis decode --parallel 4
+    $ oscura batch 'captures/*.wfm' --analysis spectrum --save-summary results.csv
+"""
+
+from __future__ import annotations
+
+import csv
+import glob
+import logging
+from pathlib import Path
+from typing import Any
+
+import click
+
+from oscura.cli.main import format_output
+
+logger = logging.getLogger("oscura.cli.batch")
+
+
+@click.command()  # type: ignore[misc]
+@click.argument("pattern")  # type: ignore[misc]
+@click.option(  # type: ignore[misc]
+    "--analysis",
+    type=click.Choice(["characterize", "decode", "spectrum"], case_sensitive=False),
+    required=True,
+    help="Type of analysis to perform on each file.",
+)
+@click.option(  # type: ignore[misc]
+    "--parallel",
+    type=int,
+    default=1,
+    help="Number of files to process concurrently (default: 1).",
+)
+@click.option(  # type: ignore[misc]
+    "--output",
+    type=click.Choice(["json", "csv", "html", "table"], case_sensitive=False),
+    default="table",
+    help="Output format (default: table).",
+)
+@click.option(  # type: ignore[misc]
+    "--save-summary",
+    type=click.Path(),
+    default=None,
+    help="Save aggregated results to file (CSV format).",
+)
+@click.option(  # type: ignore[misc]
+    "--continue-on-error",
+    is_flag=True,
+    help="Continue processing even if individual files fail.",
+)
+@click.pass_context  # type: ignore[misc]
+def batch(
+    ctx: click.Context,
+    pattern: str,
+    analysis: str,
+    parallel: int,
+    output: str,
+    save_summary: str | None,
+    continue_on_error: bool,
+) -> None:
+    """Batch process multiple files.
+
+    Processes all files matching the given pattern with the specified analysis.
+    Supports parallel processing for faster execution on multi-core systems.
+
+    Args:
+        ctx: Click context object.
+        pattern: Glob pattern to match files.
+        analysis: Type of analysis (characterize, decode, spectrum).
+        parallel: Number of parallel workers.
+        output: Output format (json, csv, html, table).
+        save_summary: Path to save CSV summary file.
+        continue_on_error: Continue processing if individual files fail.
+
+    Raises:
+        Exception: If batch processing fails or no files found.
+
+    Examples:
+
+        \b
+        # Process all WFM files with characterization
+        $ oscura batch '*.wfm' --analysis characterize
+
+        \b
+        # Parallel processing with 4 workers
+        $ oscura batch 'test_run_*/*.wfm' \\
+            --analysis characterize \\
+            --parallel 4 \\
+            --save-summary results.csv
+
+        \b
+        # Decode all captures, continue on errors
+        $ oscura batch 'captures/*.wfm' \\
+            --analysis decode \\
+            --continue-on-error
+    """
+    verbose = ctx.obj.get("verbose", 0)
+
+    if verbose:
+        logger.info(f"Batch processing pattern: {pattern}")
+        logger.info(f"Analysis type: {analysis}")
+        logger.info(f"Parallel workers: {parallel}")
+
+    try:
+        # Expand glob pattern
+        files = glob.glob(pattern, recursive=True)  # noqa: PTH207
+
+        if not files:
+            click.echo(f"No files matched pattern: {pattern}", err=True)
+            ctx.exit(1)
+
+        logger.info(f"Found {len(files)} files to process")
+
+        # Perform batch analysis
+        results = _perform_batch_analysis(
+            files=files,
+            analysis_type=analysis,
+            parallel=parallel,
+            continue_on_error=continue_on_error,
+            verbose=verbose,
+        )
+
+        # Save summary if requested
+        if save_summary:
+            _save_summary(results, save_summary)
+            logger.info(f"Summary saved to {save_summary}")
+
+        # Output aggregated results
+        summary = _generate_summary(results)
+        formatted = format_output(summary, output)
+        click.echo(formatted)
+
+    except Exception as e:
+        logger.error(f"Batch processing failed: {e}")
+        if verbose > 1:
+            raise
+        click.echo(f"Error: {e}", err=True)
+        ctx.exit(1)
+
+
+def _perform_batch_analysis(
+    files: list[str],
+    analysis_type: str,
+    parallel: int,
+    continue_on_error: bool,
+    verbose: int,
+) -> list[dict[str, Any]]:
+    """Perform batch analysis on multiple files.
+
+    Uses concurrent.futures for parallel processing when parallel > 1.
+
+    Args:
+        files: List of file paths to process.
+        analysis_type: Type of analysis to perform.
+        parallel: Number of parallel workers.
+        continue_on_error: Whether to continue on errors.
+        verbose: Verbosity level.
+
+    Returns:
+        List of result dictionaries, one per file.
+
+    Raises:
+        Exception: If analysis fails and continue_on_error is False.
+    """
+    from concurrent.futures import ThreadPoolExecutor, as_completed
+
+    def analyze_single_file(file_path: str) -> dict[str, Any]:
+        """Analyze a single file and return results.
+
+        Args:
+            file_path: Path to waveform file to analyze.
+
+        Returns:
+            Dictionary containing analysis results.
+        """
+        import numpy as np
+
+        from oscura.analyzers.waveform.measurements import fall_time, rise_time
+        from oscura.analyzers.waveform.spectral import fft, thd
+        from oscura.inference import detect_protocol
+        from oscura.loaders import load
+
+        # Load trace
+        trace = load(file_path)
+        sample_rate = trace.metadata.sample_rate
+
+        # Base result
+        result: dict[str, Any] = {
+            "file": str(Path(file_path).name),
+            "status": "success",
+            "analysis_type": analysis_type,
+            "samples": len(trace.data),  # type: ignore[union-attr]
+            "sample_rate": f"{sample_rate / 1e6:.1f} MHz",
+        }
+
+        # Add analysis-specific results
+        if analysis_type == "characterize":
+            # Pass WaveformTrace directly to functions (they expect WaveformTrace)
+            rt = rise_time(trace)  # type: ignore[arg-type]
+            ft = fall_time(trace)  # type: ignore[arg-type]
+            result.update(
+                {
+                    "rise_time": f"{rt * 1e9:.2f} ns" if not np.isnan(rt) else "N/A",
+                    "fall_time": f"{ft * 1e9:.2f} ns" if not np.isnan(ft) else "N/A",
+                }
+            )
+        elif analysis_type == "decode":
+            detected = detect_protocol(trace)  # type: ignore[arg-type]
+            result.update(
+                {
+                    "protocol": detected.get("protocol", "unknown"),
+                    "confidence": f"{detected.get('confidence', 0) * 100:.0f}%",
+                }
+            )
+        elif analysis_type == "spectrum":
+            # Pass WaveformTrace directly to FFT functions
+            freqs, mags = fft(trace)  # type: ignore[misc, arg-type]
+            if len(mags) > 0:
+                peak_idx = int(np.argmax(mags))
+                peak_freq = freqs[peak_idx]
+            else:
+                peak_freq = 0.0
+            thd_val = thd(trace)  # type: ignore[arg-type]
+            result.update(
+                {
+                    "peak_frequency": f"{peak_freq / 1e6:.3f} MHz",
+                    "thd": f"{thd_val:.1f} dB" if not np.isnan(thd_val) else "N/A",
+                }
+            )
+
+        return result
+
+    results: list[dict[str, Any]] = []
+
+    if parallel > 1:
+        # Parallel processing using ThreadPoolExecutor
+        with ThreadPoolExecutor(max_workers=parallel) as executor:
+            future_to_file = {executor.submit(analyze_single_file, f): f for f in files}
+
+            for i, future in enumerate(as_completed(future_to_file), 1):
+                file_path = future_to_file[future]
+                if verbose:
+                    logger.info(f"[{i}/{len(files)}] Completed {Path(file_path).name}")
+
+                try:
+                    result = future.result()
+                    results.append(result)
+                except Exception as e:
+                    logger.error(f"Failed to process {file_path}: {e}")
+                    if continue_on_error:
+                        results.append(
+                            {
+                                "file": str(Path(file_path).name),
+                                "status": "error",
+                                "error": str(e),
+                            }
+                        )
+                    else:
+                        raise
+    else:
+        # Sequential processing
+        for i, file_path in enumerate(files, 1):
+            if verbose:
+                logger.info(f"[{i}/{len(files)}] Processing {file_path}")
+
+            try:
+                result = analyze_single_file(file_path)
+                results.append(result)
+            except Exception as e:
+                logger.error(f"Failed to process {file_path}: {e}")
+                if continue_on_error:
+                    results.append(
+                        {
+                            "file": str(Path(file_path).name),
+                            "status": "error",
+                            "error": str(e),
+                        }
+                    )
+                else:
+                    raise
+
+    return results
+
+
+def _generate_summary(results: list[dict[str, Any]]) -> dict[str, Any]:
+    """Generate summary statistics from batch results.
+
+    Args:
+        results: List of individual file results.
+
+    Returns:
+        Summary dictionary with aggregated statistics.
+    """
+    total = len(results)
+    successful = sum(1 for r in results if r.get("status") == "success")
+    failed = total - successful
+
+    summary: dict[str, Any] = {
+        "total_files": total,
+        "successful": successful,
+        "failed": failed,
+        "success_rate": f"{successful / total * 100:.1f}%" if total > 0 else "N/A",
+    }
+
+    # Add analysis-specific aggregations
+    if results and successful > 0:
+        summary["note"] = "Detailed per-file results available in JSON/CSV output"
+
+    return summary
+
+
+def _save_summary(results: list[dict[str, Any]], output_path: str) -> None:
+    """Save batch results to CSV file.
+
+    Args:
+        results: List of result dictionaries.
+        output_path: Path to save CSV file.
+    """
+    if not results:
+        return
+
+    # Get all unique keys across all results
+    all_keys: set[str] = set()
+    for result in results:
+        all_keys.update(result.keys())
+
+    fieldnames = sorted(all_keys)
+
+    with open(output_path, "w", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(results)

oscura/cli/characterize.py

@@ -0,0 +1,273 @@
+"""TraceKit Characterize Command implementing CLI-002.
+
+Provides CLI for buffer/signal characterization with automatic logic family
+detection and optional reference comparison.
+
+
+Example:
+    $ oscura characterize 74hc04_output.wfm
+    $ oscura characterize signal.wfm --logic-family CMOS_3V3
+    $ oscura characterize signal.wfm --compare reference.wfm --output html
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from oscura.cli.main import format_output
+
+if TYPE_CHECKING:
+    from oscura.core.types import WaveformTrace
+
+logger = logging.getLogger("oscura.cli.characterize")
+
+
+@click.command()  # type: ignore[misc]
+@click.argument("file", type=click.Path(exists=True))  # type: ignore[misc]
+@click.option(  # type: ignore[misc]
+    "--type",
+    "analysis_type",
+    type=click.Choice(["buffer", "signal", "power"], case_sensitive=False),
+    default="buffer",
+    help="Type of characterization to perform.",
+)
+@click.option(  # type: ignore[misc]
+    "--logic-family",
+    type=click.Choice(
+        ["TTL", "CMOS", "CMOS_3V3", "CMOS_5V", "LVTTL", "LVCMOS", "auto"],
+        case_sensitive=False,
+    ),
+    default="auto",
+    help="Logic family for buffer characterization (default: auto-detect).",
+)
+@click.option(  # type: ignore[misc]
+    "--compare",
+    type=click.Path(exists=True),
+    default=None,
+    help="Reference file for comparison analysis.",
+)
+@click.option(  # type: ignore[misc]
+    "--output",
+    type=click.Choice(["json", "csv", "html", "table"], case_sensitive=False),
+    default="table",
+    help="Output format (default: table).",
+)
+@click.option(  # type: ignore[misc]
+    "--save-report",
+    type=click.Path(),
+    default=None,
+    help="Save HTML report to file.",
+)
+@click.pass_context  # type: ignore[misc]
+def characterize(
+    ctx: click.Context,
+    file: str,
+    analysis_type: str,
+    logic_family: str,
+    compare: str | None,
+    output: str,
+    save_report: str | None,
+) -> None:
+    """Characterize buffer, signal, or power measurements.
+
+    Analyzes a waveform file and extracts timing, quality, and performance
+    characteristics. Supports automatic logic family detection and optional
+    comparison to a reference signal.
+
+    Args:
+        ctx: Click context object.
+        file: Path to waveform file to characterize.
+        analysis_type: Type of characterization (buffer, signal, power).
+        logic_family: Logic family for buffer characterization.
+        compare: Path to reference file for comparison analysis.
+        output: Output format (json, csv, html, table).
+        save_report: Path to save HTML report file.
+
+    Raises:
+        Exception: If characterization fails or file cannot be loaded.
+
+    Examples:
+
+        \b
+        # Simple buffer characterization
+        $ oscura characterize 74hc04_output.wfm
+
+        \b
+        # Full characterization with reference
+        $ oscura characterize signal.wfm \\
+            --logic-family CMOS_3V3 \\
+            --compare golden_reference.wfm \\
+            --save-report report.html
+
+        \b
+        # Power analysis
+        $ oscura characterize power_rail.wfm --type power --output json
+    """
+    verbose = ctx.obj.get("verbose", 0)
+
+    if verbose:
+        logger.info(f"Characterizing: {file}")
+        logger.info(f"Analysis type: {analysis_type}")
+        logger.info(f"Logic family: {logic_family}")
+
+    try:
+        # Import here to avoid circular imports
+        from oscura.loaders import load
+
+        # Load the main trace
+        logger.debug(f"Loading trace from {file}")
+        trace = load(file)
+
+        # Load reference trace if provided
+        reference_trace: WaveformTrace | None = None
+        if compare:
+            logger.debug(f"Loading reference trace from {compare}")
+            reference_trace = load(compare)  # type: ignore[assignment]
+
+        # Perform characterization based on type
+        results = _perform_characterization(
+            trace=trace,
+            reference_trace=reference_trace,
+            analysis_type=analysis_type,
+            logic_family=logic_family,
+        )
+
+        # Add metadata
+        results["file"] = str(Path(file).name)
+        if compare:
+            results["reference_file"] = str(Path(compare).name)
+
+        # Generate HTML report if requested
+        if save_report:
+            html_content = format_output(results, "html")
+            with open(save_report, "w") as f:
+                f.write(html_content)
+            logger.info(f"Report saved to {save_report}")
+
+        # Output results
+        formatted = format_output(results, output)
+        click.echo(formatted)
+
+    except Exception as e:
+        logger.error(f"Characterization failed: {e}")
+        if verbose > 1:
+            raise
+        click.echo(f"Error: {e}", err=True)
+        ctx.exit(1)
+
+
+def _perform_characterization(
+    trace: Any,
+    reference_trace: Any | None,
+    analysis_type: str,
+    logic_family: str,
+) -> dict[str, Any]:
+    """Perform characterization analysis.
+
+    Calls actual TraceKit analysis functions based on the analysis type.
+
+    Args:
+        trace: Main trace to analyze.
+        reference_trace: Optional reference trace for comparison.
+        analysis_type: Type of analysis ('buffer', 'signal', 'power').
+        logic_family: Logic family for digital analysis.
+
+    Returns:
+        Dictionary of analysis results.
+    """
+    import numpy as np
+
+    from oscura.analyzers.waveform.measurements import (
+        fall_time,
+        overshoot,
+        rise_time,
+        undershoot,
+    )
+    from oscura.comparison.compare import compare_traces, similarity_score
+    from oscura.inference import detect_logic_family
+
+    sample_rate = trace.metadata.sample_rate
+    data = trace.data
+
+    results: dict[str, Any] = {
+        "analysis_type": analysis_type,
+        "logic_family": logic_family,
+        "sample_rate": f"{sample_rate / 1e6:.1f} MHz",
+        "samples": len(data),
+        "duration": f"{len(data) / sample_rate * 1e3:.3f} ms",
+    }
+
+    if analysis_type == "buffer":
+        # Buffer characterization using actual workflow (WRK-001)
+        # Functions expect WaveformTrace, not ndarray
+        rt = rise_time(trace)
+        ft = fall_time(trace)
+        os_pct = overshoot(trace)
+        us_pct = undershoot(trace)
+
+        results.update(
+            {
+                "rise_time": f"{rt * 1e9:.2f} ns" if not np.isnan(rt) else "N/A",
+                "fall_time": f"{ft * 1e9:.2f} ns" if not np.isnan(ft) else "N/A",
+                "overshoot": f"{os_pct:.1f} %" if not np.isnan(os_pct) else "N/A",
+                "undershoot": f"{us_pct:.1f} %" if not np.isnan(us_pct) else "N/A",
+                "status": "PASS",
+            }
+        )
+
+        # Logic family detection
+        if logic_family == "auto":
+            detected = detect_logic_family(trace)
+            # detect_logic_family returns dict with 'primary' key
+            primary = detected.get("primary", {})
+            results["logic_family_detected"] = primary.get("name", "unknown")
+            results["confidence"] = f"{primary.get('confidence', 0) * 100:.0f}%"
+        else:
+            results["logic_family_detected"] = logic_family
+
+    elif analysis_type == "signal":
+        # Signal analysis
+        results.update(
+            {
+                "amplitude": f"{float(data.max() - data.min()):.3f} V",
+                "peak_to_peak": f"{float(data.max() - data.min()):.3f} V",
+                "mean": f"{float(data.mean()):.3f} V",
+                "rms": f"{float(np.sqrt((data**2).mean())):.3f} V",
+            }
+        )
+
+    elif analysis_type == "power":
+        # Power analysis - compute power statistics directly from voltage
+        # Assume voltage trace, compute power (P = V^2/R, assume R=1 for relative)
+        power_data = data**2
+        avg_pwr = float(np.mean(power_data))
+        peak_pwr = float(np.max(power_data))
+        total_energy = float(np.sum(power_data) / sample_rate)
+
+        results.update(
+            {
+                "average_power": f"{avg_pwr * 1e3:.3f} mW",
+                "peak_power": f"{peak_pwr * 1e3:.3f} mW",
+                "energy": f"{total_energy * 1e6:.3f} uJ",
+            }
+        )
+
+    # Add comparison results if reference provided
+    if reference_trace is not None:
+        ref_data = reference_trace.data
+        # similarity_score expects WaveformTrace objects
+        sim = similarity_score(trace, reference_trace)
+        # compare_traces returns ComparisonResult dataclass
+        comparison_result = compare_traces(trace, reference_trace)
+
+        results["comparison"] = {
+            "correlation": f"{comparison_result.correlation:.4f}",
+            "amplitude_difference": f"{abs(float(data.mean()) - float(ref_data.mean())):.3f} V",
+            "similarity": f"{sim * 100:.1f}%",
+        }
+
+    return results