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

oscura/inference/active_learning/observation_table.py

@@ -0,0 +1,230 @@
+"""L* observation table for DFA learning.
+
+This module implements the observation table data structure used in
+Angluin's L* algorithm for active learning of deterministic finite automata.
+
+References:
+    Angluin, D. (1987). Learning regular sets from queries and counterexamples.
+    Information and Computation, 75(2), 87-106.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from oscura.inference.state_machine import FiniteAutomaton, State, Transition
+
+
+@dataclass
+class ObservationTable:
+    """L* observation table for DFA learning.
+
+    The observation table is the core data structure in the L* algorithm.
+    It maintains:
+    - S: Set of prefixes (rows of upper part)
+    - SA: Set of S + Σ (one-step extensions, lower part)
+    - E: Set of suffixes (columns/experiments)
+    - T: Table entries mapping (prefix + suffix) -> bool (accept/reject)
+
+    A table is:
+    - Closed: Every row in SA has an equivalent row in S
+    - Consistent: Identical rows in S have identical one-step extensions
+
+    Attributes:
+        S: Set of prefixes (represented as tuples of symbols)
+        E: Set of suffixes (represented as tuples of symbols)
+        T: Mapping from string (prefix+suffix) to acceptance
+        alphabet: Alphabet of symbols
+    """
+
+    S: set[tuple[str, ...]] = field(default_factory=lambda: {()})
+    E: set[tuple[str, ...]] = field(default_factory=lambda: {()})
+    T: dict[tuple[str, ...], bool] = field(default_factory=dict)
+    alphabet: set[str] = field(default_factory=set)
+
+    def row(self, s: tuple[str, ...]) -> tuple[bool, ...]:
+        """Get row for prefix s.
+
+        Returns the row in the observation table for prefix s, which
+        consists of the membership query results for s·e for each suffix e in E.
+
+        Args:
+            s: Prefix (tuple of symbols)
+
+        Returns:
+            Tuple of boolean values representing the row
+        """
+        return tuple(self.T.get(s + e, False) for e in sorted(self.E))
+
+    def is_closed(self) -> bool:
+        """Check if table is closed.
+
+        A table is closed if for every row in SA (one-step extensions),
+        there exists an equivalent row in S.
+
+        Returns:
+            True if table is closed
+        """
+        return self.find_closing_counterexample() is None
+
+    def is_consistent(self) -> bool:
+        """Check if table is consistent.
+
+        A table is consistent if for any two prefixes s1, s2 in S with
+        identical rows, all one-step extensions s1·a and s2·a also have
+        identical rows for each symbol a in the alphabet.
+
+        Returns:
+            True if table is consistent
+        """
+        return self.find_consistency_counterexample() is None
+
+    def find_closing_counterexample(self) -> tuple[str, ...] | None:
+        """Find row in SA without equivalent in S.
+
+        Searches for a string s·a where s ∈ S and a ∈ Σ such that
+        row(s·a) is not equal to row(s') for any s' ∈ S.
+
+        Returns:
+            String in SA without equivalent in S, or None if closed
+        """
+        # Get all rows in S
+        s_rows = {s: self.row(s) for s in self.S}
+
+        # Check all one-step extensions
+        for s in self.S:
+            for a in self.alphabet:
+                sa = s + (a,)
+                sa_row = self.row(sa)
+
+                # Check if this row exists in S
+                if sa_row not in s_rows.values():
+                    return sa
+
+        return None
+
+    def find_consistency_counterexample(
+        self,
+    ) -> tuple[tuple[str, ...], tuple[str, ...], str] | None:
+        """Find inconsistency in table.
+
+        Searches for two prefixes s1, s2 in S with identical rows and
+        a symbol a such that row(s1·a) ≠ row(s2·a).
+
+        Returns:
+            Tuple (s1, s2, a) representing inconsistency, or None if consistent
+        """
+        # Build mapping from rows to prefixes
+        row_to_prefixes: dict[tuple[bool, ...], list[tuple[str, ...]]] = {}
+        for s in self.S:
+            r = self.row(s)
+            if r not in row_to_prefixes:
+                row_to_prefixes[r] = []
+            row_to_prefixes[r].append(s)
+
+        # Check each equivalence class
+        for prefixes in row_to_prefixes.values():
+            if len(prefixes) < 2:
+                continue
+
+            # Check all pairs in this equivalence class
+            for i in range(len(prefixes)):
+                for j in range(i + 1, len(prefixes)):
+                    s1 = prefixes[i]
+                    s2 = prefixes[j]
+
+                    # Check each symbol
+                    for a in self.alphabet:
+                        s1a = s1 + (a,)
+                        s2a = s2 + (a,)
+
+                        if self.row(s1a) != self.row(s2a):
+                            return (s1, s2, a)
+
+        return None
+
+    def to_dfa(self) -> FiniteAutomaton:
+        """Construct hypothesis DFA from closed, consistent table.
+
+        Creates a DFA where:
+        - Each distinct row in S corresponds to a state
+        - Transitions are determined by row(s·a)
+        - Initial state corresponds to row(ε)
+        - Accepting states are those where T[s·ε] = True
+
+        Returns:
+            FiniteAutomaton constructed from table
+
+        Raises:
+            ValueError: If table is not closed or not consistent
+        """
+        if not self.is_closed():
+            raise ValueError("Table must be closed to construct DFA")
+        if not self.is_consistent():
+            raise ValueError("Table must be consistent to construct DFA")
+
+        # Map rows to state IDs
+        row_to_state: dict[tuple[bool, ...], int] = {}
+        state_to_row: dict[int, tuple[bool, ...]] = {}
+        state_representatives: dict[int, tuple[str, ...]] = {}
+
+        state_id = 0
+        for s in sorted(self.S):
+            r = self.row(s)
+            if r not in row_to_state:
+                row_to_state[r] = state_id
+                state_to_row[state_id] = r
+                state_representatives[state_id] = s
+                state_id += 1
+
+        # Create states
+        states = []
+        accepting_states = set()
+
+        for sid in range(state_id):
+            rep = state_representatives[sid]
+            # State is accepting if T[rep] = True (i.e., rep is accepted)
+            is_accepting = self.T.get(rep, False)
+            is_initial = rep == ()
+
+            state = State(
+                id=sid,
+                name=f"q{sid}",
+                is_initial=is_initial,
+                is_accepting=is_accepting,
+            )
+            states.append(state)
+
+            if is_accepting:
+                accepting_states.add(sid)
+
+        # Create transitions
+        transitions = []
+        seen_transitions = set()
+
+        for sid in range(state_id):
+            rep = state_representatives[sid]
+
+            for a in sorted(self.alphabet):
+                # Find target state
+                rep_a = rep + (a,)
+                target_row = self.row(rep_a)
+                target_state = row_to_state[target_row]
+
+                # Add transition
+                key = (sid, target_state, a)
+                if key not in seen_transitions:
+                    seen_transitions.add(key)
+                    transitions.append(Transition(source=sid, target=target_state, symbol=a))
+
+        # Find initial state
+        initial_row = self.row(())
+        initial_state = row_to_state[initial_row]
+
+        return FiniteAutomaton(
+            states=states,
+            transitions=transitions,
+            alphabet=self.alphabet.copy(),
+            initial_state=initial_state,
+            accepting_states=accepting_states,
+        )

oscura/inference/active_learning/oracle.py

@@ -0,0 +1,78 @@
+"""Oracle interface for L* active learning.
+
+This module defines the oracle interface used in the L* algorithm.
+The oracle answers membership and equivalence queries about the target DFA.
+
+References:
+    Angluin, D. (1987). Learning regular sets from queries and counterexamples.
+    Information and Computation, 75(2), 87-106.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from oscura.inference.state_machine import FiniteAutomaton  # noqa: TC001
+
+
+class Oracle(ABC):
+    """Oracle for answering membership and equivalence queries.
+
+    An oracle provides access to the target language through two types of queries:
+
+    1. Membership Query: "Is word w accepted by the target DFA?"
+       - Returns True if w is in the target language, False otherwise
+       - Must be consistent (same query always returns same answer)
+
+    2. Equivalence Query: "Is hypothesis H equivalent to the target DFA?"
+       - Returns None if H is equivalent to target
+       - Returns a counterexample word if H differs from target
+       - Counterexample is a word accepted by exactly one of H or target
+
+    The oracle also provides the alphabet of the target language.
+    """
+
+    @abstractmethod
+    def membership_query(self, word: tuple[str, ...]) -> bool:
+        """Answer membership query: Is word accepted by target DFA?
+
+        Args:
+            word: Sequence of symbols to test
+
+        Returns:
+            True if word is accepted by target language, False otherwise
+        """
+        ...
+
+    @abstractmethod
+    def equivalence_query(self, hypothesis: FiniteAutomaton) -> tuple[str, ...] | None:
+        """Answer equivalence query: Is hypothesis equivalent to target?
+
+        Args:
+            hypothesis: Proposed DFA to test for equivalence
+
+        Returns:
+            None if hypothesis is equivalent to target, otherwise a
+            counterexample word that is accepted by exactly one of
+            hypothesis or target
+        """
+        ...
+
+    @abstractmethod
+    def get_alphabet(self) -> set[str]:
+        """Get the alphabet of the target language.
+
+        Returns:
+            Set of symbols in the target alphabet
+        """
+        ...
+
+    def get_query_counts(self) -> tuple[int, int]:
+        """Get counts of membership and equivalence queries.
+
+        This is useful for analyzing the efficiency of the learning algorithm.
+
+        Returns:
+            Tuple of (membership_queries, equivalence_queries)
+        """
+        return (0, 0)  # Default implementation, can be overridden

oscura/inference/active_learning/teachers/__init__.py

@@ -0,0 +1,15 @@
+"""Teachers for L* active learning.
+
+This module provides different oracle implementations (teachers) for the
+L* algorithm. Teachers can be based on:
+
+- Simulator: Replay from captured protocol traces
+- Interactive: Live device interaction
+- Model: From formal protocol specification
+"""
+
+from oscura.inference.active_learning.teachers.simulator import SimulatorTeacher
+
+__all__ = [
+    "SimulatorTeacher",
+]

oscura/inference/active_learning/teachers/simulator.py

@@ -0,0 +1,192 @@
+"""Simulator teacher for L* active learning.
+
+This module implements an oracle that uses captured protocol traces as
+ground truth. It's useful for learning DFAs from historical data without
+requiring a live system.
+
+The simulator teacher treats traces as examples of valid protocol sequences.
+"""
+
+from __future__ import annotations
+
+from oscura.inference.active_learning.oracle import Oracle
+from oscura.inference.state_machine import FiniteAutomaton  # noqa: TC001
+
+
+class SimulatorTeacher(Oracle):
+    """Oracle that replays captured protocol traces.
+
+    This teacher uses captured message traces as ground truth for learning.
+    It answers queries based on whether sequences appear in the captured traces.
+
+    Membership queries check if a word is a valid prefix of any trace.
+    Equivalence queries test the hypothesis against all captured traces.
+
+    This is useful for:
+    - Learning from historical protocol captures
+    - Offline protocol analysis
+    - Testing L* implementation with known data
+
+    Attributes:
+        traces: List of message sequences (each trace is list of symbols)
+        alphabet: Set of all symbols appearing in traces
+        membership_query_count: Number of membership queries answered
+        equivalence_query_count: Number of equivalence queries answered
+    """
+
+    def __init__(self, traces: list[list[str]]):
+        """Initialize simulator teacher from captured traces.
+
+        Args:
+            traces: List of message sequences, where each sequence is a
+                    list of symbols (strings). All traces are treated as
+                    positive examples (accepted sequences).
+
+        Raises:
+            ValueError: If no traces provided
+        """
+        if not traces:
+            raise ValueError("Need at least one trace")
+
+        self.traces = traces
+        self.alphabet = self._extract_alphabet()
+        self.membership_query_count = 0
+        self.equivalence_query_count = 0
+
+        # Build set of all valid prefixes for efficient membership queries
+        self._valid_prefixes: set[tuple[str, ...]] = set()
+        self._build_prefix_set()
+
+    def _extract_alphabet(self) -> set[str]:
+        """Extract alphabet from all traces.
+
+        Returns:
+            Set of all unique symbols in traces
+        """
+        alphabet = set()
+        for trace in self.traces:
+            alphabet.update(trace)
+        return alphabet
+
+    def _build_prefix_set(self) -> None:
+        """Build set of all valid prefixes from traces.
+
+        Pre-computes all prefixes for efficient membership query answering.
+        """
+        for trace in self.traces:
+            # Add empty prefix
+            self._valid_prefixes.add(())
+
+            # Add all prefixes of this trace
+            for i in range(1, len(trace) + 1):
+                prefix = tuple(trace[:i])
+                self._valid_prefixes.add(prefix)
+
+    def membership_query(self, word: tuple[str, ...]) -> bool:
+        """Check if word is a valid prefix of any trace.
+
+        A word is accepted if it appears as a prefix (including the full
+        sequence) of at least one captured trace.
+
+        Args:
+            word: Sequence of symbols to test
+
+        Returns:
+            True if word is a prefix of any trace, False otherwise
+        """
+        self.membership_query_count += 1
+        return word in self._valid_prefixes
+
+    def equivalence_query(self, hypothesis: FiniteAutomaton) -> tuple[str, ...] | None:
+        """Check hypothesis against all traces.
+
+        Tests whether the hypothesis DFA correctly accepts all captured traces
+        and their prefixes. Returns a counterexample if the hypothesis disagrees
+        with the trace data.
+
+        Args:
+            hypothesis: Proposed DFA to test
+
+        Returns:
+            None if hypothesis matches all trace data, otherwise a
+            counterexample word that hypothesis classifies incorrectly
+        """
+        self.equivalence_query_count += 1
+
+        # Check all valid prefixes
+        for prefix in self._valid_prefixes:
+            hypothesis_accepts = hypothesis.accepts(list(prefix))
+            target_accepts = True  # All prefixes should be accepted
+
+            if hypothesis_accepts != target_accepts:
+                return prefix
+
+        # Also check some strings not in traces (they should be rejected)
+        # Generate some random invalid sequences
+        invalid_sequences = self._generate_invalid_sequences(hypothesis)
+
+        for seq in invalid_sequences:
+            hypothesis_accepts = hypothesis.accepts(list(seq))
+            target_accepts = seq in self._valid_prefixes
+
+            if hypothesis_accepts != target_accepts:
+                return seq
+
+        return None
+
+    def _generate_invalid_sequences(
+        self, hypothesis: FiniteAutomaton, max_checks: int = 100
+    ) -> list[tuple[str, ...]]:
+        """Generate sequences not in traces to test hypothesis.
+
+        Creates test sequences by:
+        1. Taking prefixes from traces and extending with different symbols
+        2. Creating short random sequences
+        3. Concatenating partial traces
+
+        Args:
+            hypothesis: Current hypothesis (used to guide generation)
+            max_checks: Maximum number of invalid sequences to generate
+
+        Returns:
+            List of sequences not in valid prefixes
+        """
+        invalid = []
+
+        # Strategy 1: Extend valid prefixes with unexpected symbols
+        for prefix in list(self._valid_prefixes)[:20]:  # Limit to avoid too many
+            for symbol in self.alphabet:
+                candidate = prefix + (symbol,)
+                if candidate not in self._valid_prefixes:
+                    invalid.append(candidate)
+                    if len(invalid) >= max_checks:
+                        return invalid
+
+        # Strategy 2: Create sequences from alphabet permutations
+        if len(self.alphabet) > 0:
+            alphabet_list = list(self.alphabet)
+            for i in range(min(5, len(alphabet_list))):
+                for j in range(min(5, len(alphabet_list))):
+                    candidate = (alphabet_list[i], alphabet_list[j])
+                    if candidate not in self._valid_prefixes:
+                        invalid.append(candidate)
+                        if len(invalid) >= max_checks:
+                            return invalid
+
+        return invalid
+
+    def get_alphabet(self) -> set[str]:
+        """Get the alphabet of the target language.
+
+        Returns:
+            Set of symbols extracted from traces
+        """
+        return self.alphabet.copy()
+
+    def get_query_counts(self) -> tuple[int, int]:
+        """Get counts of membership and equivalence queries.
+
+        Returns:
+            Tuple of (membership_queries, equivalence_queries)
+        """
+        return (self.membership_query_count, self.equivalence_query_count)