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

oscura/automotive/can/session.py

@@ -7,8 +7,7 @@ provides discovery-oriented analysis workflows.
 
 from __future__ import annotations
 
-from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import pandas as pd
 
@@ -18,42 +17,53 @@ from oscura.automotive.can.models import (
     CANMessageList,
     MessageAnalysis,
 )
-from oscura.automotive.can.patterns import (
-    MessagePair,
-    MessageSequence,
-    PatternAnalyzer,
-    TemporalCorrelation,
-)
+from oscura.sessions.base import AnalysisSession, ComparisonResult
 
 if TYPE_CHECKING:
     from oscura.automotive.can.message_wrapper import CANMessageWrapper
+    from oscura.automotive.can.patterns import (
+        MessagePair,
+        MessageSequence,
+        TemporalCorrelation,
+    )
     from oscura.automotive.can.stimulus_response import StimulusResponseReport
     from oscura.inference.state_machine import FiniteAutomaton
 
 __all__ = ["CANSession"]
 
 
-class CANSession:
+class CANSession(AnalysisSession):
     """CAN bus reverse engineering session.
 
     This is the primary API for discovering and analyzing unknown CAN bus
-    protocols. It provides:
+    protocols. It extends AnalysisSession to provide unified interface for
+    multi-session workflows with CAN-specific functionality.
+
+    Features:
+    - Recording management (add/remove/compare recordings)
     - Message inventory and filtering
     - Per-message statistical analysis
     - Discovery-oriented workflows
     - Hypothesis testing
     - Documentation generation
-
-    Example - Discovery workflow:
-        >>> session = CANSession.from_log("capture.blf")
+    - Pattern discovery (pairs, sequences, correlations)
+    - State machine inference
+
+    Example - Basic usage:
+        >>> from oscura.sessions import CANSession
+        >>> from oscura.acquisition import FileSource
+        >>> session = CANSession(name="Vehicle Analysis")
+        >>> session.add_recording("baseline", FileSource("idle.blf"))
         >>> inventory = session.inventory()
         >>> print(inventory)
-        >>>
+
+    Example - Discovery workflow:
+        >>> session = CANSession(name="Brake Analysis")
+        >>> session.add_recording("data", FileSource("capture.blf"))
         >>> # Focus on a specific message
         >>> msg = session.message(0x280)
         >>> analysis = msg.analyze()
         >>> print(analysis.summary())
-        >>>
         >>> # Test hypothesis
         >>> hypothesis = msg.test_hypothesis(
         ...     signal_name="rpm",
@@ -62,51 +72,31 @@ class CANSession:
         ...     scale=0.25
         ... )
 
-    Example - Known protocol decoding:
-        >>> session = CANSession.from_log("capture.blf")
-        >>> from oscura.automotive.dbc import load_dbc
-        >>> dbc = load_dbc("vehicle.dbc")
-        >>> decoded = session.decode(dbc)
+    Example - Compare recordings:
+        >>> session = CANSession(name="Brake Analysis")
+        >>> session.add_recording("no_brake", FileSource("idle.blf"))
+        >>> session.add_recording("brake_pressed", FileSource("brake.blf"))
+        >>> result = session.compare("no_brake", "brake_pressed")
+        >>> print(f"Changed messages: {result.changed_bytes}")
     """
 
-    def __init__(self, messages: CANMessageList | None = None):
+    def __init__(self, name: str = "CAN Session"):
         """Initialize CAN session.
 
         Args:
-            messages: Initial message collection (optional).
-        """
-        self._messages = messages or CANMessageList()
-        self._analyses_cache: dict[int, MessageAnalysis] = {}
-
-    @classmethod
-    def from_log(cls, file_path: Path | str) -> CANSession:
-        """Create session from automotive log file.
-
-        Automatically detects file format (BLF, ASC, MDF, CSV) and loads.
-
-        Args:
-            file_path: Path to log file.
-
-        Returns:
-            New CANSession with loaded messages.
-        """
-        from oscura.automotive.loaders import load_automotive_log
-
-        messages = load_automotive_log(file_path)
-        return cls(messages=messages)
-
-    @classmethod
-    def from_messages(cls, messages: list[CANMessage]) -> CANSession:
-        """Create session from list of CAN messages.
+            name: Session name (default: "CAN Session").
 
-        Args:
-            messages: List of CAN messages.
-
-        Returns:
-            New CANSession.
+        Example:
+            >>> from oscura.sessions import CANSession
+            >>> from oscura.acquisition import FileSource
+            >>> session = CANSession(name="Vehicle Analysis")
+            >>> session.add_recording("baseline", FileSource("idle.blf"))
+            >>> session.add_recording("active", FileSource("running.blf"))
+            >>> results = session.analyze()
         """
-        msg_list = CANMessageList(messages=messages)
-        return cls(messages=msg_list)
+        super().__init__(name=name)
+        self._messages = CANMessageList()
+        self._analyses_cache: dict[int, MessageAnalysis] = {}
 
     def inventory(self) -> pd.DataFrame:
         """Generate message inventory.
@@ -218,6 +208,11 @@ class CANSession:
 
         Returns:
             New CANSession with filtered messages.
+
+        Note:
+            This creates a new session with filtered messages from the current
+            internal message collection. This method is primarily for legacy
+            workflows. For new code, use add_recording() with separate files.
         """
         filtered_messages = []
 
@@ -265,7 +260,10 @@ class CANSession:
                 msg for msg in filtered_messages if msg.arbitration_id in valid_ids
             ]
 
-        return CANSession.from_messages(filtered_messages)
+        # Create new session with filtered messages
+        new_session = CANSession(name=f"{self.name} (filtered)")
+        new_session._messages = CANMessageList(messages=filtered_messages)
+        return new_session
 
     def unique_ids(self) -> set[int]:
         """Get set of unique CAN IDs in this session.
@@ -287,6 +285,185 @@ class CANSession:
         """Return total number of messages."""
         return len(self._messages)
 
+    def analyze(self) -> dict[str, Any]:
+        """Perform comprehensive CAN protocol analysis.
+
+        Implements the AnalysisSession abstract method. Analyzes all messages
+        in the current session to discover signals, patterns, and protocol structure.
+
+        Returns:
+            Dictionary with analysis results:
+            - inventory: Message inventory DataFrame
+            - num_messages: Total number of messages
+            - num_unique_ids: Number of unique CAN IDs
+            - time_range: Tuple of (start, end) timestamps
+            - message_analyses: Dict mapping CAN ID to MessageAnalysis
+            - patterns: Discovered patterns (pairs, sequences, correlations)
+
+        Example:
+            >>> from oscura.sessions import CANSession
+            >>> from oscura.acquisition import FileSource
+            >>> session = CANSession(name="Analysis")
+            >>> session.add_recording("data", FileSource("capture.blf"))
+            >>> results = session.analyze()
+            >>> print(f"Found {results['num_unique_ids']} unique CAN IDs")
+            >>> print(f"Duration: {results['time_range'][1] - results['time_range'][0]:.2f}s")
+
+        Note:
+            This is the unified AnalysisSession interface. For CAN-specific
+            workflows, use inventory(), message(), and other domain methods.
+        """
+        # Generate inventory
+        inventory = self.inventory()
+
+        # Analyze all unique IDs
+        message_analyses = {}
+        for arb_id in self.unique_ids():
+            try:
+                analysis = self.analyze_message(arb_id)
+                message_analyses[arb_id] = analysis
+            except Exception:
+                # Skip messages that fail analysis
+                continue
+
+        # Find patterns (if enough messages)
+        patterns: dict[str, Any] = {}
+        if len(self._messages) >= 10:
+            try:
+                patterns["message_pairs"] = self.find_message_pairs(
+                    time_window_ms=100, min_occurrence=3
+                )
+                patterns["temporal_correlations"] = self.find_temporal_correlations(
+                    max_delay_ms=100
+                )
+            except Exception:
+                # Pattern analysis is optional
+                pass
+
+        return {
+            "inventory": inventory,
+            "num_messages": len(self._messages),
+            "num_unique_ids": len(self.unique_ids()),
+            "time_range": self.time_range() if len(self._messages) > 0 else (0.0, 0.0),
+            "message_analyses": message_analyses,
+            "patterns": patterns,
+        }
+
+    def compare(self, name1: str, name2: str) -> ComparisonResult:
+        """Compare two CAN recordings (stimulus-response analysis).
+
+        Overrides AnalysisSession.compare() to provide CAN-specific differential
+        analysis. Compares two recordings to detect changed messages, byte-level
+        differences, and signal variations.
+
+        Args:
+            name1: Name of first recording (baseline).
+            name2: Name of second recording (stimulus).
+
+        Returns:
+            ComparisonResult with CAN-specific differences:
+            - changed_bytes: Number of message-bytes that differ
+            - changed_regions: List of (message_id, byte_offset, description)
+            - similarity_score: Overall similarity (0.0 to 1.0)
+            - details: CAN-specific details (changed_ids, byte_changes, etc.)
+
+        Example:
+            >>> from oscura.acquisition import FileSource
+            >>> session = CANSession(name="Brake Analysis")
+            >>> session.add_recording("no_brake", FileSource("idle.blf"))
+            >>> session.add_recording("brake_pressed", FileSource("brake.blf"))
+            >>> result = session.compare("no_brake", "brake_pressed")
+            >>> print(f"Changed messages: {result.details['changed_message_ids']}")
+
+        Note:
+            This uses the unified AnalysisSession interface. For advanced
+            CAN-specific comparison, use compare_to() method.
+        """
+        # Load recordings as CANSession instances
+        recording1 = self._recording_to_session(name1)
+        recording2 = self._recording_to_session(name2)
+
+        # Use CAN-specific stimulus-response analysis
+        from oscura.automotive.can.stimulus_response import StimulusResponseAnalyzer
+
+        analyzer = StimulusResponseAnalyzer()
+        report = analyzer.detect_responses(recording1, recording2)
+
+        # Convert to ComparisonResult
+        changed_message_ids = report.changed_messages
+        total_byte_changes = sum(len(changes) for changes in report.byte_changes.values())
+
+        # Build changed regions list (message_id, byte_offset, description)
+        changed_regions = []
+        for msg_id, changes in report.byte_changes.items():
+            for change in changes:
+                changed_regions.append(
+                    (
+                        msg_id,
+                        change.byte_position,
+                        f"Magnitude: {change.change_magnitude:.2f}",
+                    )
+                )
+
+        # Calculate similarity (1.0 = identical, 0.0 = completely different)
+        total_unique_ids = len(recording1.unique_ids().union(recording2.unique_ids()))
+        if total_unique_ids > 0:
+            similarity = 1.0 - (len(changed_message_ids) / total_unique_ids)
+        else:
+            similarity = 1.0
+
+        return ComparisonResult(
+            recording1=name1,
+            recording2=name2,
+            changed_bytes=total_byte_changes,
+            changed_regions=changed_regions,  # type: ignore[arg-type]
+            similarity_score=similarity,
+            details={
+                "changed_message_ids": changed_message_ids,
+                "byte_changes": report.byte_changes,
+                "new_messages": report.new_messages,
+                "disappeared_messages": report.disappeared_messages,
+                "stimulus_response_report": report,
+            },
+        )
+
+    def _recording_to_session(self, name: str) -> CANSession:
+        """Convert a recording to a CANSession instance.
+
+        Args:
+            name: Recording name.
+
+        Returns:
+            CANSession loaded from the recording.
+
+        Raises:
+            KeyError: If recording not found.
+            ValueError: If recording is not a valid CAN log file.
+        """
+        if name not in self.recordings:
+            available = list(self.recordings.keys())
+            raise KeyError(f"Recording '{name}' not found. Available: {available}")
+
+        source, _ = self.recordings[name]
+
+        # Get file path from source and load messages
+        # FileSource has a 'path' attribute
+        if hasattr(source, "path"):
+            from oscura.automotive.loaders import load_automotive_log
+
+            file_path = source.path
+            messages = load_automotive_log(file_path)
+
+            # Create new session and populate with messages
+            session = CANSession(name=name)
+            session._messages = messages
+            return session
+        else:
+            raise ValueError(
+                f"Recording '{name}' is not from a file source. "
+                "Recording-based comparison requires FileSource."
+            )
+
     def compare_to(self, other_session: CANSession) -> StimulusResponseReport:
         """Compare this session to another to detect changes.
 
@@ -300,24 +477,22 @@ class CANSession:
         Returns:
             StimulusResponseReport with detected changes.
 
-        Example - Brake pedal analysis:
-            >>> baseline = CANSession.from_log("no_brake.blf")
-            >>> stimulus = CANSession.from_log("brake_pressed.blf")
+        Note:
+            For comparing recordings within a session, use compare() instead:
+            >>> session.compare("baseline", "stimulus")
+
+            This method is for comparing two separate CANSession instances.
+
+        Example:
+            >>> # Compare two session instances directly
+            >>> baseline = CANSession(name="Baseline")
+            >>> stimulus = CANSession(name="Stimulus")
+            >>> # ... populate sessions with messages ...
             >>> report = baseline.compare_to(stimulus)
             >>> print(report.summary())
             >>> # Show which messages changed
             >>> for msg_id in report.changed_messages:
-            ...     print(f"0x{msg_id:03X} responded to brake press")
-
-        Example - Throttle position analysis:
-            >>> idle = CANSession.from_log("idle.blf")
-            >>> throttle = CANSession.from_log("throttle_50pct.blf")
-            >>> report = idle.compare_to(throttle)
-            >>> # Examine byte-level changes
-            >>> for msg_id, changes in report.byte_changes.items():
-            ...     print(f"Message 0x{msg_id:03X}:")
-            ...     for change in changes:
-            ...         print(f"  Byte {change.byte_position}: {change.change_magnitude:.2f}")
+            ...     print(f"0x{msg_id:03X} responded")
         """
         from oscura.automotive.can.stimulus_response import (
             StimulusResponseAnalyzer,
@@ -344,11 +519,16 @@ class CANSession:
             List of MessagePair objects, sorted by occurrence count.
 
         Example:
-            >>> session = CANSession.from_log("capture.blf")
+            >>> from oscura.sessions import CANSession
+            >>> from oscura.acquisition import FileSource
+            >>> session = CANSession(name="Pattern Analysis")
+            >>> session.add_recording("data", FileSource("capture.blf"))
             >>> pairs = session.find_message_pairs(time_window_ms=50)
             >>> for pair in pairs[:5]:
             ...     print(pair)
         """
+        from oscura.automotive.can.patterns import PatternAnalyzer
+
         return PatternAnalyzer.find_message_pairs(
             self, time_window_ms=time_window_ms, min_occurrence=min_occurrence
         )
@@ -373,7 +553,10 @@ class CANSession:
             List of MessageSequence objects, sorted by support.
 
         Example:
-            >>> session = CANSession.from_log("startup.blf")
+            >>> from oscura.sessions import CANSession
+            >>> from oscura.acquisition import FileSource
+            >>> session = CANSession(name="Sequence Analysis")
+            >>> session.add_recording("data", FileSource("startup.blf"))
             >>> sequences = session.find_message_sequences(
             ...     max_sequence_length=3,
             ...     time_window_ms=1000
@@ -381,6 +564,8 @@ class CANSession:
             >>> for seq in sequences[:5]:
             ...     print(seq)
         """
+        from oscura.automotive.can.patterns import PatternAnalyzer
+
         return PatternAnalyzer.find_message_sequences(
             self,
             max_sequence_length=max_sequence_length,
@@ -404,11 +589,16 @@ class CANSession:
             Dictionary mapping (leader_id, follower_id) to correlation info.
 
         Example:
-            >>> session = CANSession.from_log("capture.blf")
+            >>> from oscura.sessions import CANSession
+            >>> from oscura.acquisition import FileSource
+            >>> session = CANSession(name="Correlation Analysis")
+            >>> session.add_recording("data", FileSource("capture.blf"))
             >>> correlations = session.find_temporal_correlations(max_delay_ms=50)
             >>> for (leader, follower), corr in correlations.items():
             ...     print(f"0x{leader:03X} → 0x{follower:03X}: {corr.avg_delay_ms:.2f}ms")
         """
+        from oscura.automotive.can.patterns import PatternAnalyzer
+
         return PatternAnalyzer.find_temporal_correlations(self, max_delay_ms=max_delay_ms)
 
     def learn_state_machine(
@@ -427,7 +617,10 @@ class CANSession:
             Learned finite automaton representing the state machine.
 
         Example:
-            >>> session = CANSession.from_log("ignition_cycles.blf")
+            >>> from oscura.sessions import CANSession
+            >>> from oscura.acquisition import FileSource
+            >>> session = CANSession(name="State Machine Learning")
+            >>> session.add_recording("data", FileSource("ignition_cycles.blf"))
             >>> automaton = session.learn_state_machine(
             ...     trigger_ids=[0x280],
             ...     context_window_ms=500
@@ -444,9 +637,15 @@ class CANSession:
         """Human-readable representation."""
         num_messages = len(self._messages)
         num_ids = len(self.unique_ids())
-        time_start, time_end = self.time_range()
-        duration = time_end - time_start
-
-        return (
-            f"CANSession({num_messages} messages, {num_ids} unique IDs, duration={duration:.2f}s)"
-        )
+        num_recordings = len(self.recordings)
+
+        if num_messages > 0:
+            time_start, time_end = self.time_range()
+            duration = time_end - time_start
+            return (
+                f"CANSession(name={self.name!r}, {num_messages} messages, "
+                f"{num_ids} unique IDs, duration={duration:.2f}s, "
+                f"recordings={num_recordings})"
+            )
+        else:
+            return f"CANSession(name={self.name!r}, recordings={num_recordings})"

oscura/automotive/can/state_machine.py

@@ -73,7 +73,9 @@ class CANStateMachine:
     - State-dependent message patterns
 
     Example - Learn ignition sequence:
-        >>> session = CANSession.from_log("ignition_cycles.blf")
+        >>> from oscura.automotive.sources import FileSource
+        >>> session = CANSession(name="Ignition Analysis")
+        >>> session.add_recording("cycles", FileSource("ignition_cycles.blf"))
         >>> sm = CANStateMachine()
         >>> # Use ignition-related CAN IDs as triggers
         >>> automaton = sm.learn_from_session(
@@ -85,7 +87,8 @@ class CANStateMachine:
         >>> print(automaton.to_dot())
 
     Example - Discover initialization sequence:
-        >>> session = CANSession.from_log("ecu_startup.blf")
+        >>> session = CANSession(name="ECU Startup")
+        >>> session.add_recording("startup", FileSource("ecu_startup.blf"))
         >>> sm = CANStateMachine()
         >>> # Use diagnostic messages as triggers
         >>> automaton = sm.learn_from_session(

oscura/builders/__init__.py

@@ -7,7 +7,7 @@ generation without manual numpy operations.
 Example:
     >>> import oscura as osc
     >>> # Simple sine wave with noise
-    >>> signal = (osc.SignalBuilder(sample_rate=1e6, duration=0.01)
+    >>> trace = (osc.SignalBuilder(sample_rate=1e6, duration=0.01)
     ...     .add_sine(frequency=1000, amplitude=1.0)
     ...     .add_noise(snr_db=40)
     ...     .build())
@@ -19,23 +19,21 @@ Example:
     ...     .build())
     >>>
     >>> # Multi-channel SPI transaction
-    >>> spi = (osc.SignalBuilder(sample_rate=10e6)
-    ...     .add_spi(clock_freq=1e6, data_mosi=b"\\x9F\\x00\\x00")
-    ...     .build())
+    >>> builder = osc.SignalBuilder(sample_rate=10e6)
+    >>> builder.add_spi(clock_freq=1e6, data_mosi=b"\\x9F\\x00\\x00")
+    >>> channels = builder.build_channels()  # Returns dict[str, WaveformTrace]
+
+API:
+    - SignalBuilder.build() returns WaveformTrace for single-channel signals
+    - SignalBuilder.build_channels() returns dict[str, WaveformTrace] for multi-channel
 
 References:
     - Oscura Signal Generation Guide
     - Protocol Test Signal Specifications
 """
 
-from oscura.builders.signal_builder import (
-    GeneratedSignal,
-    SignalBuilder,
-    SignalMetadata,
-)
+from oscura.builders.signal_builder import SignalBuilder
 
 __all__ = [
-    "GeneratedSignal",
     "SignalBuilder",
-    "SignalMetadata",
 ]