oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/automotive/can/message_wrapper.py

@@ -180,94 +180,28 @@ class CANMessageWrapper:
             >>> print(result.summary())
         """
         # Create signal definition
-        definition = SignalDefinition(
-            name=signal_name,
-            start_bit=start_byte * 8,
-            length=bit_length,
-            byte_order=byte_order,
-            value_type=value_type,
-            scale=scale,
-            offset=offset,
-            unit=unit,
+        definition = _create_signal_definition(
+            signal_name, start_byte, bit_length, byte_order, value_type, scale, offset, unit
         )
 
-        # Get all messages with this ID
-        filtered = self._session._messages.filter_by_id(self._arbitration_id)
-
         # Decode all values
-        decoded_values = []
-        for msg in filtered.messages:
-            try:
-                value = definition.decode(msg.data)
-                decoded_values.append(value)
-            except Exception:
-                # Skip messages that can't be decoded
-                pass
+        decoded_values = _decode_hypothesis_values(self._session, self._arbitration_id, definition)
 
+        # Handle no decoded values
         if not decoded_values:
-            return HypothesisResult(
-                signal_name=signal_name,
-                definition=definition,
-                values=[],
-                min_value=0.0,
-                max_value=0.0,
-                mean=0.0,
-                std=0.0,
-                is_valid=False,
-                confidence=0.0,
-                feedback="Failed to decode any messages with this definition",
-            )
+            return _create_failed_hypothesis_result(signal_name, definition)
 
         # Calculate statistics
-        arr = np.array(decoded_values)
-        min_val = float(np.min(arr))
-        max_val = float(np.max(arr))
-        mean_val = float(np.mean(arr))
-        std_val = float(np.std(arr))
+        stats = _calculate_hypothesis_statistics(decoded_values)
 
         # Validate hypothesis
-        is_valid = True
-        confidence = 1.0
-        feedback_parts = []
-
-        # Check expected range if provided
-        if expected_min is not None and min_val < expected_min:
-            is_valid = False
-            confidence *= 0.5
-            feedback_parts.append(f"Min value {min_val:.2f} below expected {expected_min:.2f}")
-
-        if expected_max is not None and max_val > expected_max:
-            is_valid = False
-            confidence *= 0.5
-            feedback_parts.append(f"Max value {max_val:.2f} above expected {expected_max:.2f}")
-
-        # Check for reasonable value distribution
-        if std_val == 0:
-            confidence *= 0.7
-            feedback_parts.append("Warning: All values are identical - might be a constant field")
-
-        # Check for extremely large range (might indicate wrong scaling)
-        value_range = max_val - min_val
-        if value_range > 1e6:
-            confidence *= 0.6
-            feedback_parts.append("Warning: Very large value range - check scaling factor")
-
-        # Positive feedback
-        if is_valid and not feedback_parts:
-            feedback_parts.append(f"Values in expected range [{min_val:.2f}, {max_val:.2f}]")
-            if std_val > 0:
-                feedback_parts.append("Signal shows variation - likely represents real data")
-
-        feedback = "; ".join(feedback_parts) if feedback_parts else "Hypothesis test passed"
+        is_valid, confidence, feedback = _validate_hypothesis(stats, expected_min, expected_max)
 
         return HypothesisResult(
             signal_name=signal_name,
             definition=definition,
             values=decoded_values,
-            min_value=min_val,
-            max_value=max_val,
-            mean=mean_val,
-            std=std_val,
+            **stats,
             is_valid=is_valid,
             confidence=confidence,
             feedback=feedback,
@@ -373,3 +307,116 @@ class CANMessageWrapper:
     def __repr__(self) -> str:
         """Human-readable representation."""
         return f"CANMessageWrapper(id=0x{self._arbitration_id:03X}, documented_signals={len(self._documented_signals)})"
+
+
+def _create_signal_definition(
+    signal_name: str,
+    start_byte: int,
+    bit_length: int,
+    byte_order: Literal["big_endian", "little_endian"],
+    value_type: Literal["unsigned", "signed", "float"],
+    scale: float,
+    offset: float,
+    unit: str,
+) -> SignalDefinition:
+    """Create signal definition from parameters."""
+    return SignalDefinition(
+        name=signal_name,
+        start_bit=start_byte * 8,
+        length=bit_length,
+        byte_order=byte_order,
+        value_type=value_type,
+        scale=scale,
+        offset=offset,
+        unit=unit,
+    )
+
+
+def _decode_hypothesis_values(
+    session: CANSession, arbitration_id: int, definition: SignalDefinition
+) -> list[float]:
+    """Decode all values using signal definition."""
+
+    filtered = session._messages.filter_by_id(arbitration_id)
+    decoded_values = []
+    for msg in filtered.messages:
+        try:
+            value = definition.decode(msg.data)
+            decoded_values.append(value)
+        except Exception:
+            pass
+    return decoded_values
+
+
+def _create_failed_hypothesis_result(
+    signal_name: str, definition: SignalDefinition
+) -> HypothesisResult:
+    """Create result for failed decoding."""
+    return HypothesisResult(
+        signal_name=signal_name,
+        definition=definition,
+        values=[],
+        min_value=0.0,
+        max_value=0.0,
+        mean=0.0,
+        std=0.0,
+        is_valid=False,
+        confidence=0.0,
+        feedback="Failed to decode any messages with this definition",
+    )
+
+
+def _calculate_hypothesis_statistics(decoded_values: list[float]) -> dict[str, float]:
+    """Calculate statistics for decoded values."""
+    arr = np.array(decoded_values)
+    return {
+        "min_value": float(np.min(arr)),
+        "max_value": float(np.max(arr)),
+        "mean": float(np.mean(arr)),
+        "std": float(np.std(arr)),
+    }
+
+
+def _validate_hypothesis(
+    stats: dict[str, float], expected_min: float | None, expected_max: float | None
+) -> tuple[bool, float, str]:
+    """Validate hypothesis and generate feedback."""
+    is_valid = True
+    confidence = 1.0
+    feedback_parts = []
+
+    # Check expected range
+    if expected_min is not None and stats["min_value"] < expected_min:
+        is_valid = False
+        confidence *= 0.5
+        feedback_parts.append(
+            f"Min value {stats['min_value']:.2f} below expected {expected_min:.2f}"
+        )
+
+    if expected_max is not None and stats["max_value"] > expected_max:
+        is_valid = False
+        confidence *= 0.5
+        feedback_parts.append(
+            f"Max value {stats['max_value']:.2f} above expected {expected_max:.2f}"
+        )
+
+    # Check value distribution
+    if stats["std"] == 0:
+        confidence *= 0.7
+        feedback_parts.append("Warning: All values are identical - might be a constant field")
+
+    value_range = stats["max_value"] - stats["min_value"]
+    if value_range > 1e6:
+        confidence *= 0.6
+        feedback_parts.append("Warning: Very large value range - check scaling factor")
+
+    # Positive feedback
+    if is_valid and not feedback_parts:
+        feedback_parts.append(
+            f"Values in expected range [{stats['min_value']:.2f}, {stats['max_value']:.2f}]"
+        )
+        if stats["std"] > 0:
+            feedback_parts.append("Signal shows variation - likely represents real data")
+
+    feedback = "; ".join(feedback_parts) if feedback_parts else "Hypothesis test passed"
+    return is_valid, confidence, feedback

oscura/automotive/can/patterns.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from collections import defaultdict
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
@@ -233,7 +233,13 @@ class PatternAnalyzer:
         Raises:
             ValueError: If max_sequence_length is invalid (<2 or >10) or
                 min_support is not in range [0.0, 1.0].
+
+        Example:
+            >>> from oscura.automotive.can import CANSession
+            >>> session = CANSession()
+            >>> sequences = PatternAnalyzer.find_message_sequences(session, max_sequence_length=3)
         """
+        # Validate parameters
         if max_sequence_length < 2:
             raise ValueError("max_sequence_length must be at least 2")
         if max_sequence_length > 10:
@@ -242,25 +248,61 @@ class PatternAnalyzer:
             raise ValueError("min_support must be between 0.0 and 1.0")
 
         time_window_s = time_window_ms / 1000.0
-
-        # Get all messages sorted by timestamp
         all_messages = sorted(session._messages.messages, key=lambda m: m.timestamp)
 
         if not all_messages:
             return []
 
-        # Find maximum message frequency (for support calculation)
+        # Calculate maximum message frequency for support calculation
+        max_count = PatternAnalyzer._calculate_max_message_frequency(all_messages)
+
+        # Mine sequences from message stream
+        sequences = PatternAnalyzer._mine_sequences(
+            all_messages, max_sequence_length, time_window_s
+        )
+
+        # Build and filter result objects
+        result = PatternAnalyzer._build_sequence_results(sequences, max_count, min_support)
+
+        # Sort by support (descending), then by occurrences
+        result.sort(key=lambda s: (s.support, s.occurrences), reverse=True)
+
+        return result
+
+    @staticmethod
+    def _calculate_max_message_frequency(messages: list[Any]) -> int:
+        """Calculate maximum message frequency for support calculation.
+
+        Args:
+            messages: List of CAN messages.
+
+        Returns:
+            Maximum frequency of any message ID.
+        """
         id_counts: dict[int, int] = defaultdict(int)
-        for msg in all_messages:
+        for msg in messages:
             id_counts[msg.arbitration_id] += 1
-        max_count = max(id_counts.values()) if id_counts else 1
+        return max(id_counts.values()) if id_counts else 1
 
-        # Mine sequences of increasing length
+    @staticmethod
+    def _mine_sequences(
+        all_messages: list[Any],
+        max_sequence_length: int,
+        time_window_s: float,
+    ) -> dict[tuple[int, ...], list[list[float]]]:
+        """Mine message sequences from CAN message stream.
+
+        Args:
+            all_messages: Sorted list of CAN messages.
+            max_sequence_length: Maximum sequence length.
+            time_window_s: Time window in seconds.
+
+        Returns:
+            Dictionary mapping sequence IDs to timing lists.
+        """
         sequences: dict[tuple[int, ...], list[list[float]]] = defaultdict(list)
 
-        # Start with 2-message sequences
         for i, msg_a in enumerate(all_messages):
-            # Look forward in time window
             sequence_start = msg_a.timestamp
             current_sequence = [msg_a.arbitration_id]
             timing = []
@@ -276,6 +318,8 @@ class PatternAnalyzer:
                 # Record sequences of desired length
                 if 2 <= len(current_sequence) <= max_sequence_length:
                     seq_key = tuple(current_sequence)
+                    # NECESSARY COPY: timing list reused across iterations.
+                    # Without .copy(), all sequences would reference final state.
                     sequences[seq_key].append(timing.copy())
 
                 # Update for next iteration
@@ -283,7 +327,24 @@ class PatternAnalyzer:
                 if len(current_sequence) >= max_sequence_length:
                     break
 
-        # Build MessageSequence objects
+        return sequences
+
+    @staticmethod
+    def _build_sequence_results(
+        sequences: dict[tuple[int, ...], list[list[float]]],
+        max_count: int,
+        min_support: float,
+    ) -> list[MessageSequence]:
+        """Build MessageSequence objects from mined sequences.
+
+        Args:
+            sequences: Dictionary mapping sequence IDs to timing lists.
+            max_count: Maximum message frequency (for support calculation).
+            min_support: Minimum support threshold.
+
+        Returns:
+            List of MessageSequence objects that meet support threshold.
+        """
         result = []
         for seq_ids, timing_lists in sequences.items():
             occurrences = len(timing_lists)
@@ -291,14 +352,7 @@ class PatternAnalyzer:
 
             if support >= min_support:
                 # Calculate average timing between consecutive messages
-                avg_timing = []
-                if timing_lists:
-                    # timing_lists[i] has len(seq_ids) - 1 elements
-                    num_gaps = len(seq_ids) - 1
-                    for gap_idx in range(num_gaps):
-                        gap_times = [t[gap_idx] for t in timing_lists if gap_idx < len(t)]
-                        if gap_times:
-                            avg_timing.append(float(np.mean(gap_times)))
+                avg_timing = PatternAnalyzer._calculate_average_timing(seq_ids, timing_lists)
 
                 result.append(
                     MessageSequence(
@@ -309,11 +363,34 @@ class PatternAnalyzer:
                     )
                 )
 
-        # Sort by support (descending), then by occurrences
-        result.sort(key=lambda s: (s.support, s.occurrences), reverse=True)
-
         return result
 
+    @staticmethod
+    def _calculate_average_timing(
+        seq_ids: tuple[int, ...],
+        timing_lists: list[list[float]],
+    ) -> list[float]:
+        """Calculate average timing between consecutive messages in sequence.
+
+        Args:
+            seq_ids: Sequence of message IDs.
+            timing_lists: List of timing lists for each occurrence.
+
+        Returns:
+            List of average timings for each gap in sequence.
+        """
+        avg_timing: list[float] = []
+        if not timing_lists:
+            return avg_timing
+
+        num_gaps = len(seq_ids) - 1
+        for gap_idx in range(num_gaps):
+            gap_times = [t[gap_idx] for t in timing_lists if gap_idx < len(t)]
+            if gap_times:
+                avg_timing.append(float(np.mean(gap_times)))
+
+        return avg_timing
+
     @staticmethod
     def find_temporal_correlations(
         session: CANSession,