sofic 0.1.0__py3-none-any.whl

sofic/automata/base.py

@@ -0,0 +1,161 @@
+"""Labeled finite automata base class."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Hashable, Iterator, Sequence
+from typing import TYPE_CHECKING, Any
+
+from sofic.base import StateMachine
+from sofic.graph import ATTR_SYMBOL, EPSILON
+
+if TYPE_CHECKING:
+    from sofic.automata.dfa import DFA
+    from sofic.automata.nfa import NFA
+
+
+class LabeledAutomaton(StateMachine):
+    """Finite-word recognizer over an input alphabet."""
+
+    input_alphabet: frozenset[Any]
+    initial_states: frozenset[Hashable]
+    accepting_states: frozenset[Hashable]
+
+    def __init__(
+        self,
+        input_alphabet: frozenset[Any] | None = None,
+        initial_states: frozenset[Hashable] | None = None,
+        accepting_states: frozenset[Hashable] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.input_alphabet = input_alphabet if input_alphabet is not None else frozenset()
+        self.initial_states = initial_states if initial_states is not None else frozenset()
+        self.accepting_states = accepting_states if accepting_states is not None else frozenset()
+
+    def validate(self) -> None:
+        for state in self.initial_states | self.accepting_states:
+            self._require(self.graph.has_state(state), f"missing state {state!r}")
+        for transition in self.transitions():
+            symbol = transition.data.get(ATTR_SYMBOL)
+            if symbol is not None and symbol is not EPSILON:
+                self._require(symbol in self.input_alphabet, f"symbol {symbol!r} not in input alphabet")
+
+    @abstractmethod
+    def recognizes(self, word: Sequence[Any]) -> bool:
+        """Return whether ``word`` is accepted."""
+
+    def words_of_length(self, length: int) -> Iterator[tuple[Any, ...]]:
+        """Yield accepted words of exactly ``length`` symbols."""
+        from sofic.automata.enumeration import words_of_length
+
+        yield from words_of_length(self, length)
+
+    def iter_language(self, max_length: int | None = None) -> Iterator[tuple[Any, ...]]:
+        """Yield accepted words in nondecreasing length order.
+
+        If ``max_length`` is omitted, the iterator is unbounded and may not
+        terminate for finite languages after yielding their last word.
+        """
+        from sofic.automata.enumeration import iter_language
+
+        yield from iter_language(self, max_length=max_length)
+
+    def to_regex(self) -> str:
+        """Return a regular expression for the accepted language."""
+        from sofic.automata.regex import automaton_to_regex
+
+        return automaton_to_regex(self)
+
+    def union(self, other: LabeledAutomaton) -> NFA:
+        """Return an NFA recognizing the union of this language and ``other``."""
+        from sofic.automata.languages.automaton_ops import union_nfa
+
+        return union_nfa(self, other)
+
+    def intersection(self, other: LabeledAutomaton) -> DFA:
+        """Return a DFA recognizing the intersection with ``other``."""
+        from sofic.automata.languages.automaton_ops import intersection_dfa
+
+        return intersection_dfa(self, other)
+
+    def intersect(self, other: LabeledAutomaton) -> DFA:
+        """Alias for :meth:`intersection`."""
+        return self.intersection(other)
+
+    def complement(self, alphabet: frozenset[Any] | None = None) -> DFA:
+        """Return a complete DFA recognizing the complement over ``alphabet``."""
+        from sofic.automata.languages.automaton_ops import complement_dfa
+
+        return complement_dfa(self, self.input_alphabet if alphabet is None else alphabet)
+
+    def difference(self, other: LabeledAutomaton, alphabet: frozenset[Any] | None = None) -> DFA:
+        """Return a DFA recognizing this language minus ``other``."""
+        from sofic.automata.languages.automaton_ops import difference_dfa
+
+        return difference_dfa(self, other, alphabet=alphabet)
+
+    def concat(self, other: LabeledAutomaton) -> NFA:
+        """Return an NFA recognizing concatenation with ``other``."""
+        from sofic.automata.languages.automaton_ops import concat_nfa
+
+        return concat_nfa(self, other)
+
+    def concatenate(self, other: LabeledAutomaton) -> NFA:
+        """Alias for :meth:`concat`."""
+        return self.concat(other)
+
+    def kleene_star(self) -> NFA:
+        """Return an NFA recognizing the Kleene star of this language."""
+        from sofic.automata.languages.automaton_ops import kleene_star_nfa
+
+        return kleene_star_nfa(self)
+
+    def star(self) -> NFA:
+        """Alias for :meth:`kleene_star`."""
+        return self.kleene_star()
+
+    def is_deterministic(self) -> bool:
+        """Return whether this automaton is DFA-deterministic."""
+        from sofic.properties import is_deterministic_automaton
+
+        return is_deterministic_automaton(self)
+
+    def delta(self, state: Hashable, symbol: Any) -> set[Hashable]:
+        targets: set[Hashable] = set()
+        for transition in self.graph.out_transitions(state):
+            if transition.data.get(ATTR_SYMBOL) == symbol:
+                targets.add(transition.target)
+        return targets
+
+    def epsilon_closure(self, states: set[Hashable]) -> set[Hashable]:
+        closure = set(states)
+        stack = list(states)
+        while stack:
+            state = stack.pop()
+            for target in self.delta(state, EPSILON):
+                if target not in closure:
+                    closure.add(target)
+                    stack.append(target)
+        return closure
+
+    def _run_nfa(self, word: Sequence[Any], start: set[Hashable] | None = None) -> set[Hashable]:
+        seed = set(self.initial_states) if start is None else set(start)
+        current = self.epsilon_closure(seed)
+        for symbol in word:
+            next_states: set[Hashable] = set()
+            for state in current:
+                next_states.update(self.delta(state, symbol))
+            current = self.epsilon_closure(next_states)
+        return current
+
+    def reverse(self) -> NFA:
+        """Return an NFA recognizing the reversed language."""
+        from sofic.automata.nfa import NFA
+
+        return NFA(
+            input_alphabet=self.input_alphabet,
+            initial_states=frozenset(self.accepting_states),
+            accepting_states=frozenset(self.epsilon_closure(set(self.initial_states))),
+            graph=self.graph.reverse(),
+        )

sofic/automata/buchi.py

@@ -0,0 +1,23 @@
+"""Büchi automata for infinite-word recognition."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from sofic.automata.nfa import NFA
+
+
+class BuchiAutomaton(NFA):
+    """ω-automaton with Büchi acceptance on ultimately periodic inputs."""
+
+    def accepts_lasso(self, prefix: Sequence[Any], loop: Sequence[Any]) -> bool:
+        """Accept if infinitely repeating ``loop`` after ``prefix`` visits accepting states infinitely often."""
+        from sofic.automata.buchi_simulation import accepts_lasso_buchi
+
+        return accepts_lasso_buchi(self, prefix, loop)
+
+    def accepts_omega(self, word: Sequence[Any]) -> bool:
+        from sofic.automata.buchi_simulation import accepts_omega_buchi
+
+        return accepts_omega_buchi(self, word)

sofic/automata/buchi_simulation.py

@@ -0,0 +1,67 @@
+"""Büchi acceptance for lasso and ultimately periodic ω-words."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Sequence
+from typing import Any
+
+from sofic.automata.buchi import BuchiAutomaton
+
+
+def accepts_lasso_buchi(ba: BuchiAutomaton, prefix: Sequence[Any], loop: Sequence[Any]) -> bool:
+    """Accept if repeating ``loop`` after ``prefix`` visits an accepting state infinitely often."""
+    post = ba._run_nfa(prefix)
+    if not post:
+        return False
+
+    reachable = _loop_closure(ba, post, loop)
+    candidates = reachable & ba.accepting_states
+    if not candidates:
+        return False
+
+    return any(_can_revisit_on_loop(ba, state, loop) for state in candidates)
+
+
+def accepts_omega_buchi(ba: BuchiAutomaton, word: Sequence[Any]) -> bool:
+    """Accept ultimately periodic ω-words represented as ``(prefix, loop)``."""
+    if (
+        len(word) == 2
+        and not isinstance(word, (str, bytes))
+        and isinstance(word[0], Sequence)
+        and not isinstance(word[0], (str, bytes))
+        and isinstance(word[1], Sequence)
+        and not isinstance(word[1], (str, bytes))
+    ):
+        return accepts_lasso_buchi(ba, word[0], word[1])
+    raise NotImplementedError("BuchiAutomaton.accepts_omega supports ultimately periodic inputs as (prefix, loop) only")
+
+
+def _loop_closure(ba: BuchiAutomaton, start: set[Hashable], loop: Sequence[Any]) -> set[Hashable]:
+    """States reachable from ``start`` by reading ``loop`` zero or more times."""
+    if not loop:
+        return set(start)
+
+    reachable = set(start)
+    frontier = set(start)
+    while frontier:
+        after = ba._run_nfa(loop, start=frontier)
+        new = after - reachable
+        if not new:
+            break
+        reachable |= new
+        frontier = new
+    return reachable
+
+
+def _can_revisit_on_loop(ba: BuchiAutomaton, state: Hashable, loop: Sequence[Any]) -> bool:
+    """Return whether ``state`` can be revisited by reading ``loop`` one or more times."""
+    if not loop:
+        return False
+
+    current = {state}
+    limit = max(len(list(ba.states())), 1) + 1
+    for _ in range(limit):
+        current = ba._run_nfa(loop, start=current)
+        if state in current:
+            return True
+    return False

sofic/automata/canonical_dual.py

@@ -0,0 +1,18 @@
+"""Dual constructions between canonical RFSA and maximized prime átomaton."""
+
+from __future__ import annotations
+
+from sofic.automata.atomaton import MaximizedPrimeAtomaton
+from sofic.automata.rfsa import CanonicalRFSA
+
+
+def dual_atomaton_from_rfsa(rfsa: CanonicalRFSA) -> MaximizedPrimeAtomaton:
+    from sofic.automata.canonical_extraction import maximized_prime_atomaton_from_language
+
+    return maximized_prime_atomaton_from_language(rfsa)
+
+
+def dual_rfsa_from_atomaton(atomaton: MaximizedPrimeAtomaton) -> CanonicalRFSA:
+    from sofic.automata.canonical_extraction import canonical_rfsa_from_language
+
+    return canonical_rfsa_from_language(atomaton)

sofic/automata/canonical_extraction.py

@@ -0,0 +1,122 @@
+"""Canonical automaton extraction from languages and observation tables."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sofic.automata.atomaton import Atomaton, MaximizedPrimeAtomaton
+from sofic.automata.dfa import DFA
+from sofic.automata.languages.automaton_ops import (
+    minimal_dfa_from_language,
+)
+from sofic.automata.languages.base import AutomatonLanguage, RegularLanguage, as_language
+from sofic.automata.nfa import NFA
+from sofic.automata.observation import ObservationTable
+from sofic.automata.rfsa import CanonicalRFSA
+
+
+def _language_automaton(language: RegularLanguage | NFA | DFA) -> NFA | DFA:
+    if isinstance(language, (NFA, DFA)):
+        return language
+    lang = as_language(language)  # type: ignore[arg-type]
+    if isinstance(lang, AutomatonLanguage):
+        return lang.automaton
+    raise TypeError(f"cannot extract automaton from {type(language)!r}")
+
+
+def canonical_rfsa_from_language(language: RegularLanguage | NFA | DFA) -> CanonicalRFSA:
+    """Build canonical RFSA from prime residuals of the language.
+
+    Phase 2 placeholder: currently reuses the minimal DFA structure directly.
+    """
+    aut = _language_automaton(language)
+    dfa = minimal_dfa_from_language(aut)
+    return CanonicalRFSA(
+        input_alphabet=dfa.input_alphabet,
+        initial_states=dfa.initial_states,
+        accepting_states=dfa.accepting_states,
+        graph=dfa.graph.copy(),
+    )
+
+
+def atomaton_from_language(language: RegularLanguage | NFA | DFA) -> Atomaton:
+    """Build átomaton via double-reversal pipeline."""
+    aut = _language_automaton(language)
+    dfa = minimal_dfa_from_language(aut)
+    rev = dfa.reverse().determinize().minimize()
+    atom = rev.reverse().determinize()
+    return Atomaton(
+        input_alphabet=atom.input_alphabet,
+        initial_states=atom.initial_states,
+        accepting_states=atom.accepting_states,
+        graph=atom.graph.copy(),
+    )
+
+
+def maximized_prime_atomaton_from_language(language: RegularLanguage | NFA | DFA) -> MaximizedPrimeAtomaton:
+    """Build maximized prime átomaton from a language.
+
+    Phase 2 placeholder: currently reuses the minimal DFA structure directly.
+    """
+    aut = _language_automaton(language)
+    lang = AutomatonLanguage(minimal_dfa_from_language(aut))
+    return MaximizedPrimeAtomaton(
+        input_alphabet=lang.automaton.input_alphabet,
+        initial_states=lang.automaton.initial_states,
+        accepting_states=lang.automaton.accepting_states,
+        graph=lang.automaton.graph.copy(),
+    )
+
+
+def observation_to_minimal_dfa(table: ObservationTable) -> DFA:
+    """Angluin-style DFA extraction from a closed, consistent table."""
+    access = sorted(table.access_words, key=lambda w: (len(w), w))
+    experiments = sorted(table.experiments, key=lambda w: (len(w), w))
+
+    def signature(word: tuple[Any, ...]) -> tuple[bool, ...]:
+        return tuple(table.membership.get(word + exp, False) for exp in experiments)
+
+    classes: dict[tuple[bool, ...], tuple[Any, ...]] = {}
+    for word in access:
+        sig = signature(word)
+        classes.setdefault(sig, word)
+
+    state_for_word = {word: classes[signature(word)] for word in access}
+    alphabet = _infer_alphabet(table)
+    dfa = DFA(
+        input_alphabet=alphabet,
+        initial_states=frozenset({()}),
+        accepting_states=frozenset(),
+    )
+    for word in access:
+        dfa.graph.add_state(state_for_word[word])
+    for word in access:
+        for symbol in alphabet:
+            target_word = word + (symbol,)
+            if target_word in state_for_word:
+                dfa.add_transition(state_for_word[word], state_for_word[target_word], symbol)
+    accepting = {state_for_word[word] for word in access if table.membership.get(word, False)}
+    dfa.accepting_states = frozenset(accepting)
+    return dfa
+
+
+def observation_to_canonical_rfsa(table: ObservationTable) -> CanonicalRFSA:
+    dfa = observation_to_minimal_dfa(table)
+    return canonical_rfsa_from_language(dfa)
+
+
+def observation_to_atomaton(table: ObservationTable) -> Atomaton:
+    dfa = observation_to_minimal_dfa(table)
+    return atomaton_from_language(dfa)
+
+
+def observation_to_maximized_prime_atomaton(table: ObservationTable) -> MaximizedPrimeAtomaton:
+    dfa = observation_to_minimal_dfa(table)
+    return maximized_prime_atomaton_from_language(dfa)
+
+
+def _infer_alphabet(table: ObservationTable) -> frozenset[Any]:
+    symbols: set[Any] = set()
+    for word in table.access_words | table.experiments:
+        symbols.update(word)
+    return frozenset(symbols)

sofic/automata/dfa.py

@@ -0,0 +1,85 @@
+"""Deterministic finite automata."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from sofic.automata.base import LabeledAutomaton
+from sofic.exceptions import NonDeterministicError
+from sofic.graph import ATTR_SYMBOL, EPSILON
+
+if TYPE_CHECKING:
+    from sofic.automata.algorithms import MinimizationAlgorithm
+    from sofic.automata.nfa import NFA
+
+
+class DFA(LabeledAutomaton):
+    """Deterministic finite automaton."""
+
+    def validate(self) -> None:
+        super().validate()
+        self._check_determinism()
+
+    def _check_determinism(self) -> None:
+        if self.is_deterministic():
+            return
+        for transition in self.transitions():
+            if transition.data.get(ATTR_SYMBOL) is EPSILON:
+                raise NonDeterministicError("DFA does not allow epsilon transitions")
+        if len(self.initial_states) != 1:
+            raise NonDeterministicError("DFA requires exactly one initial state")
+        seen: dict[tuple[Hashable, Any], Hashable] = {}
+        for transition in self.transitions():
+            symbol = transition.data.get(ATTR_SYMBOL)
+            if symbol is None:
+                continue
+            key = (transition.source, symbol)
+            if key in seen and seen[key] != transition.target:
+                raise NonDeterministicError(f"non-deterministic transition on {key}")
+            seen[key] = transition.target
+        raise NonDeterministicError("DFA determinism check failed")
+
+    def add_transition(self, source: Hashable, target: Hashable, symbol: Any, **attrs: Any) -> int:
+        if symbol is EPSILON:
+            raise NonDeterministicError("DFA does not allow epsilon transitions")
+        key = (source, symbol)
+        for transition in self.graph.out_transitions(source):
+            if transition.data.get(ATTR_SYMBOL) == symbol and transition.target != target:
+                raise NonDeterministicError(f"non-deterministic transition on {key}")
+        return self.graph.add_transition(source, target, **{ATTR_SYMBOL: symbol, **attrs})
+
+    def recognizes(self, word: Sequence[Any]) -> bool:
+        if not self.initial_states:
+            return False
+        state = next(iter(self.initial_states))
+        for symbol in word:
+            successors = self.delta(state, symbol)
+            if len(successors) != 1:
+                return False
+            state = next(iter(successors))
+        return state in self.accepting_states
+
+    def determinize(self) -> DFA:
+        from sofic.automata.algorithms import trim
+
+        return trim(self)
+
+    @classmethod
+    def from_nfa(cls, nfa: NFA, **kwargs: Any) -> DFA:
+        from sofic.automata.algorithms import determinize
+        from sofic.automata.nfa import NFA as _NFA
+
+        if not isinstance(nfa, _NFA):
+            raise TypeError("from_nfa requires an NFA")
+        return determinize(nfa)
+
+    def minimize(
+        self,
+        algorithm: MinimizationAlgorithm = "hopcroft",
+        *,
+        alphabet: frozenset[Any] | None = None,
+    ) -> DFA:
+        from sofic.automata.algorithms import minimize
+
+        return minimize(self, algorithm=algorithm, alphabet=alphabet)

sofic/automata/dfasat.py

@@ -0,0 +1,195 @@
+"""Exact minimal-DFA identification via a SAT encoding (DFASAT-style).
+
+Given labeled positive/negative sample words, this finds the **minimal** number
+of states of any DFA consistent with the sample -- the exact optimum that the
+RPNI/EDSM heuristics only approximate. Following Heule & Verwer
+:cite:`HeuleVerwer2010`, the augmented prefix-tree acceptor (APTA) is translated
+into a graph-colouring SAT instance -- one Boolean per (APTA node, colour), plus
+accepting-colour and transition variables -- and an external SAT solver is asked
+whether a ``k``-colouring exists. The search runs ``k`` upward from a lower bound
+to the EDSM upper bound (:func:`sofic.automata.edsm.learn_dfa_edsm`); the first
+satisfiable ``k`` is the provably minimal DFA.
+
+This requires the optional `python-sat <https://pysathq.github.io/>`_ dependency
+(``pip install sofic[sat]``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Sequence
+from typing import Any
+
+from sofic.automata.dfa import DFA
+from sofic.automata.edsm import _ACCEPT, _REJECT, _build_apta, _collect_alphabet, learn_dfa_edsm
+
+__all__ = ["learn_dfa_sat"]
+
+
+def _require_pysat() -> Any:
+    try:
+        from pysat.formula import CNF, IDPool
+        from pysat.solvers import Solver
+    except ImportError as exc:  # pragma: no cover - optional dependency
+        raise ImportError(
+            "learn_dfa_sat requires the optional 'python-sat' dependency; install with pip install sofic[sat]"
+        ) from exc
+    return CNF, IDPool, Solver
+
+
+def _encode(
+    label: Sequence[int],
+    trans: Sequence[dict[Any, int]],
+    alphabet: Sequence[Any],
+    k: int,
+    cnf_cls: Any,
+    pool: Any,
+) -> Any:
+    """Build the graph-colouring CNF for a ``k``-state consistent DFA."""
+    cnf = cnf_cls()
+    n = len(label)
+    sym_index = {symbol: s for s, symbol in enumerate(alphabet)}
+
+    def x(v: int, i: int) -> int:
+        return pool.id(("x", v, i))
+
+    def a(i: int) -> int:
+        return pool.id(("a", i))
+
+    def y(s: int, i: int, j: int) -> int:
+        return pool.id(("y", s, i, j))
+
+    # (1) each APTA node gets at least one colour.
+    for v in range(n):
+        cnf.append([x(v, i) for i in range(k)])
+    # (2) ... and at most one.
+    for v in range(n):
+        for i in range(k):
+            for j in range(i + 1, k):
+                cnf.append([-x(v, i), -x(v, j)])
+    # (3) accepting / rejecting consistency of the colour.
+    for v in range(n):
+        if label[v] == _ACCEPT:
+            for i in range(k):
+                cnf.append([-x(v, i), a(i)])
+        elif label[v] == _REJECT:
+            for i in range(k):
+                cnf.append([-x(v, i), -a(i)])
+    # symmetry break: the root (APTA node 0) is colour 0.
+    cnf.append([x(0, 0)])
+    # (4) APTA edges force the coloured transition relation.
+    for v in range(n):
+        for symbol, w in trans[v].items():
+            s = sym_index[symbol]
+            for i in range(k):
+                for j in range(k):
+                    cnf.append([-x(v, i), -x(w, j), y(s, i, j)])
+    # (5) the transition relation is a partial function (at most one target).
+    for s in range(len(alphabet)):
+        for i in range(k):
+            for j1 in range(k):
+                for j2 in range(j1 + 1, k):
+                    cnf.append([-y(s, i, j1), -y(s, i, j2)])
+
+    return cnf, x, a, y, sym_index
+
+
+def _decode(
+    model: set[int],
+    label: Sequence[int],
+    trans: Sequence[dict[Any, int]],
+    alphabet: Sequence[Any],
+    k: int,
+    x: Any,
+    a: Any,
+    y: Any,
+    sym_index: dict[Any, int],
+) -> DFA:
+    n = len(label)
+    colour_of = {}
+    for v in range(n):
+        for i in range(k):
+            if x(v, i) in model:
+                colour_of[v] = i
+                break
+
+    used = sorted(set(colour_of.values()) | {0})
+    names: dict[int, Hashable] = {colour: f"q{colour}" for colour in used}
+
+    dfa = DFA(input_alphabet=frozenset(alphabet))
+    for name in names.values():
+        dfa.graph.add_state(name)
+
+    seen: set[tuple[int, Any]] = set()
+    for v in range(n):
+        i = colour_of[v]
+        for symbol, w in trans[v].items():
+            j = colour_of[w]
+            key = (i, symbol)
+            if key in seen:
+                continue
+            seen.add(key)
+            dfa.add_transition(names[i], names[j], symbol)
+
+    dfa.initial_states = frozenset({names[colour_of[0]]})
+    dfa.accepting_states = frozenset(names[i] for i in used if a(i) in model)
+    dfa.validate()
+    return dfa
+
+
+def learn_dfa_sat(
+    positive: Sequence[Sequence[Any]],
+    negative: Sequence[Sequence[Any]] | None = None,
+    *,
+    lower_bound: int = 1,
+    upper_bound: int | None = None,
+    solver_name: str = "g3",
+) -> DFA:
+    """Learn the exact minimal DFA consistent with labeled samples via SAT.
+
+    Parameters
+    ----------
+    positive
+        Words that must be accepted.
+    negative
+        Words that must be rejected.
+    lower_bound
+        Smallest state count to try (default ``1``).
+    upper_bound
+        Largest state count to try. Defaults to the number of states of the
+        EDSM hypothesis (:func:`sofic.automata.edsm.learn_dfa_edsm`), which is a
+        valid upper bound on the minimum.
+    solver_name
+        Any `python-sat <https://pysathq.github.io/>`_ solver name (default
+        ``"g3"`` for Glucose 3).
+
+    Returns
+    -------
+    DFA
+        The provably minimal DFA consistent with the sample
+        :cite:`HeuleVerwer2010`.
+    """
+    cnf_cls, id_pool, solver_cls = _require_pysat()
+
+    pos = [tuple(word) for word in positive]
+    neg = [tuple(word) for word in (negative or ())]
+    if not pos and not neg:
+        raise ValueError("at least one positive or negative sample is required")
+
+    alphabet = _collect_alphabet(pos, neg)
+    label, trans = _build_apta(pos, neg)
+
+    if upper_bound is None:
+        upper_bound = len(list(learn_dfa_edsm(pos, neg).states()))
+    lower_bound = max(1, int(lower_bound))
+    if upper_bound < lower_bound:
+        upper_bound = lower_bound
+
+    for k in range(lower_bound, upper_bound + 1):
+        pool = id_pool()
+        cnf, x, a, y, sym_index = _encode(label, trans, alphabet, k, cnf_cls, pool)
+        with solver_cls(name=solver_name, bootstrap_with=cnf.clauses) as solver:
+            if solver.solve():
+                model = {lit for lit in solver.get_model() if lit > 0}
+                return _decode(model, label, trans, alphabet, k, x, a, y, sym_index)
+
+    raise RuntimeError(f"no consistent DFA with at most {upper_bound} states (unexpected; check the sample)")