"""Signal classification and measurement intelligence for Oscura.

This package provides intelligent signal type detection, quality assessment,
and measurement suitability checking to help users understand why they might
get NaN results and which measurements are appropriate for their signals.

The package is organized into focused submodules:
    - detection: Low-level signal detection utilities (digital, periodicity, edges)
    - classification: Signal type classification (classify_signal)
    - quality: Signal quality assessment (assess_signal_quality)
    - suitability: Measurement suitability checking (check_measurement_suitability)
    - suggestions: Measurement suggestion engine (suggest_measurements)
    - recommendations: Analysis recommendation system (recommend_analyses)

Example:
    >>> import oscura as osc
    >>> trace = osc.load('signal.wfm')
    >>> classification = osc.classify_signal(trace)
    >>> print(f"Signal type: {classification['type']}")
    >>> print(f"Characteristics: {classification['characteristics']}")
    >>> quality = osc.assess_signal_quality(trace)
    >>> print(f"SNR: {quality['snr']:.1f} dB")
    >>> suggestions = osc.suggest_measurements(trace)
    >>> print(f"Recommended measurements: {suggestions}")

References:
    IEEE 181-2011: Standard for Transitional Waveform Definitions
    IEEE 1057-2017: Standard for Digitizing Waveform Recorders
"""

# Classification
from oscura.inference.signal_intelligence.classification import classify_signal

# Detection utilities (exposed for testing)
from oscura.inference.signal_intelligence.detection import (
    _count_edges,
    _detect_digital_signal,
    _detect_edge_periodicity,
    _detect_periodicity,
    _detect_periodicity_fft,
    _estimate_noise_level,
)

# Quality assessment
from oscura.inference.signal_intelligence.quality import assess_signal_quality

# Recommendations
from oscura.inference.signal_intelligence.recommendations import (
    AnalysisRecommendation,
    get_optimal_domain_order,
    recommend_analyses,
)

# Suggestions
from oscura.inference.signal_intelligence.suggestions import suggest_measurements

# Suitability checking
from oscura.inference.signal_intelligence.suitability import (
    check_measurement_suitability,
)

__all__ = [
    # Public API
    "AnalysisRecommendation",
    # Private functions exposed for testing
    "_count_edges",
    "_detect_digital_signal",
    "_detect_edge_periodicity",
    "_detect_periodicity",
    "_detect_periodicity_fft",
    "_estimate_noise_level",
    "assess_signal_quality",
    "check_measurement_suitability",
    "classify_signal",
    "get_optimal_domain_order",
    "recommend_analyses",
    "suggest_measurements",
]
