Restructure modules: sofic.inference and automata subpackages (4/5)

docs/automata/atomaton.rst

@@ -1,5 +1,5 @@
 .. atomaton.rst
-.. py:module:: sofic.automata.atomaton
+.. py:module:: sofic.automata.canonical.atomaton
 
 ********
 Átomaton
@@ -29,7 +29,7 @@ the special case where the reverse is deterministic.
 
 .. code-block:: python
 
-    from sofic.automata.atomaton import Atomaton, atomic_states, is_atomic
+    from sofic.automata.canonical.atomaton import Atomaton, atomic_states, is_atomic
 
     atomaton = Atomaton.from_language(dfa)
     is_atomic(atomaton)          # True
@@ -58,4 +58,4 @@ API
 .. autoclass:: MaximizedPrimeAtomaton
    :members: from_language, from_canonical_rfsa, dual
 
-.. autofunction:: sofic.automata.canonical_extraction.maximized_prime_atomaton_from_language
+.. autofunction:: sofic.automata.canonical.residual.maximized_prime_atomaton_from_language

docs/automata/icdfa.rst

@@ -1,5 +1,5 @@
 .. icdfa.rst
-.. py:module:: sofic.automata.icdfa
+.. py:module:: sofic.automata.enumeration.icdfa
 
 *****
 ICDFA
@@ -23,7 +23,7 @@ API
 .. autofunction:: count_icdfa
 .. autofunction:: count_icdfa_empty
 
-.. autofunction:: sofic.automata.idfa.iter_idfa_strings
-.. autofunction:: sofic.automata.idfa.rank_idfa_string
-.. autofunction:: sofic.automata.idfa.unrank_idfa_string
-.. autofunction:: sofic.automata.idfa.count_accessible_idfa
+.. autofunction:: sofic.automata.enumeration.idfa.iter_idfa_strings
+.. autofunction:: sofic.automata.enumeration.idfa.rank_idfa_string
+.. autofunction:: sofic.automata.enumeration.idfa.unrank_idfa_string
+.. autofunction:: sofic.automata.enumeration.idfa.count_accessible_idfa

docs/automata/learning.rst

@@ -1,5 +1,5 @@
 .. learning.rst
-.. py:module:: sofic.automata.learning
+.. py:module:: sofic.automata.learning.nlstar
 
 ********
 Learning
@@ -18,25 +18,25 @@ hypothesis is the canonical RFSA of the target (:doc:`rfsa`). Running NL\* on
 the reversed target and reversing the result learns the maximized prime
 átomaton (:doc:`atomaton`).
 
-:class:`~sofic.automata.active.AutomatonEquivalenceOracle` answers equivalence
+:class:`~sofic.automata.learning.active.AutomatonEquivalenceOracle` answers equivalence
 queries exactly against a target automaton, returning a shortest
 counterexample.
 
-.. autofunction:: sofic.automata.learning.learn_rfsa_nlstar
-.. autofunction:: sofic.automata.learning.learn_prime_atomaton_nlstar
-.. autofunction:: sofic.automata.learning.learn_rfsa_from_language
+.. autofunction:: sofic.automata.learning.nlstar.learn_rfsa_nlstar
+.. autofunction:: sofic.automata.learning.nlstar.learn_prime_atomaton_nlstar
+.. autofunction:: sofic.automata.learning.nlstar.learn_rfsa_from_language
 
 Active learning (L\*, TTT, Mealy)
 =================================
 
-:mod:`sofic.automata.active` learns an automaton from a *teacher* answering
+:mod:`sofic.automata.learning.active` learns an automaton from a *teacher* answering
 **membership** and **equivalence** queries. It provides Angluin's L\*
 :cite:`Angluin1987` and a redundancy-free **discrimination-tree** learner in the
 TTT family :cite:`KearnsVazirani1994,Isberner2014` for
 :class:`~sofic.automata.dfa.DFA`, plus the Mealy variant of L\*
 :cite:`Shahbaz2009`; all use Rivest-Schapire counterexample analysis
 :cite:`RivestSchapire1993`. Oracles adapt sofic models: a
-:class:`~sofic.automata.active.LanguageMembershipOracle` wraps any model exposing
+:class:`~sofic.automata.learning.active.LanguageMembershipOracle` wraps any model exposing
 ``recognizes`` / ``__contains__`` (a :class:`~sofic.automata.dfa.DFA`, NFA,
 átomaton, or ``model.to_support_dfa()`` for a sofic shift or ε-machine), and the
 equivalence oracles offer bounded-exhaustive or random-walk testing.
@@ -53,7 +53,7 @@ equivalence test:
 
 .. code-block:: python
 
-   from sofic.automata.active import (
+   from sofic.automata.learning.active import (
        FunctionMembershipOracle,
        RandomWalkEquivalenceOracle,
        learn_dfa_lstar,
@@ -63,23 +63,23 @@ equivalence test:
    equivalence = RandomWalkEquivalenceOracle(membership, {"a", "b"}, rng=0)
    dfa = learn_dfa_lstar({"a", "b"}, membership, equivalence)
 
-.. autofunction:: sofic.automata.active.learn_dfa_lstar
-.. autofunction:: sofic.automata.active.learn_dfa_ttt
-.. autofunction:: sofic.automata.active.learn_mealy_lstar
-.. autofunction:: sofic.automata.active.learn_dfa_from_language
-.. autofunction:: sofic.automata.active.learn_mealy_from_transducer
+.. autofunction:: sofic.automata.learning.active.learn_dfa_lstar
+.. autofunction:: sofic.automata.learning.active.learn_dfa_ttt
+.. autofunction:: sofic.automata.learning.active.learn_mealy_lstar
+.. autofunction:: sofic.automata.learning.active.learn_dfa_from_language
+.. autofunction:: sofic.automata.learning.active.learn_mealy_from_transducer
 
-.. autoclass:: sofic.automata.active.MembershipOracle
+.. autoclass:: sofic.automata.learning.active.MembershipOracle
    :members:
-.. autoclass:: sofic.automata.active.EquivalenceOracle
+.. autoclass:: sofic.automata.learning.active.EquivalenceOracle
    :members:
-.. autoclass:: sofic.automata.active.LanguageMembershipOracle
-.. autoclass:: sofic.automata.active.FunctionMembershipOracle
-.. autoclass:: sofic.automata.active.AutomatonEquivalenceOracle
-.. autoclass:: sofic.automata.active.ExhaustiveEquivalenceOracle
-.. autoclass:: sofic.automata.active.RandomWalkEquivalenceOracle
-.. autoclass:: sofic.automata.active.TransducerOutputOracle
-.. autoclass:: sofic.automata.active.MealyExhaustiveEquivalenceOracle
+.. autoclass:: sofic.automata.learning.active.LanguageMembershipOracle
+.. autoclass:: sofic.automata.learning.active.FunctionMembershipOracle
+.. autoclass:: sofic.automata.learning.active.AutomatonEquivalenceOracle
+.. autoclass:: sofic.automata.learning.active.ExhaustiveEquivalenceOracle
+.. autoclass:: sofic.automata.learning.active.RandomWalkEquivalenceOracle
+.. autoclass:: sofic.automata.learning.active.TransducerOutputOracle
+.. autoclass:: sofic.automata.learning.active.MealyExhaustiveEquivalenceOracle
 
 Passive learning (RPNI)
 =======================
@@ -95,7 +95,7 @@ consistent with the sample :cite:`Lang1998`:
    dfa = learn_dfa_rpni(positive=["ab", "abab"], negative=["a", "b"])
    dfa.validate()
 
-.. autofunction:: sofic.automata.rpni.learn_dfa_rpni
+.. autofunction:: sofic.automata.learning.rpni.learn_dfa_rpni
 
 Passive learning (EDSM / blue-fringe)
 =====================================
@@ -116,12 +116,12 @@ automaton:
    dfa = learn_dfa_edsm(positive=["a", "aba", "ababa"], negative=["", "b", "ab"])
    dfa.validate()
 
-.. autofunction:: sofic.automata.edsm.learn_dfa_edsm
+.. autofunction:: sofic.automata.learning.edsm.learn_dfa_edsm
 
 Exact minimal DFA (SAT)
 =======================
 
-Where RPNI and EDSM are heuristics, :func:`sofic.automata.dfasat.learn_dfa_sat`
+Where RPNI and EDSM are heuristics, :func:`sofic.automata.learning.dfasat.learn_dfa_sat`
 returns the **provably minimal** DFA consistent with the sample. Following Heule
 & Verwer :cite:`HeuleVerwer2010`, it translates the augmented prefix-tree
 acceptor into a graph-colouring SAT instance and searches the state count ``k``
@@ -136,7 +136,7 @@ satisfiable ``k``. It requires the optional `python-sat
    dfa = learn_dfa_sat(positive=["a", "aba", "ababa"], negative=["", "b", "ab"])
    dfa.validate()
 
-.. autofunction:: sofic.automata.dfasat.learn_dfa_sat
+.. autofunction:: sofic.automata.learning.dfasat.learn_dfa_sat
 
 Probabilistic passive learning (ALERGIA)
 ========================================
@@ -146,7 +146,7 @@ from **unlabeled** positive strings by merging states of a frequency
 prefix-tree acceptor whenever a Hoeffding-bound test cannot distinguish their
 transition statistics :cite:`Carrasco1994`. It is the stochastic, unlabeled
 counterpart of RPNI/EDSM and a state-merging alternative to CSSR
-(:func:`sofic.generators.epsilon_inference.cssr`). The compatibility threshold
+(:func:`sofic.inference.cssr.process.cssr`). The compatibility threshold
 ``alpha`` trades off model size against fidelity: smaller ``alpha`` merges more
 aggressively (fewer states); larger ``alpha`` is more conservative.
 
@@ -159,13 +159,13 @@ aggressively (fewer states); larger ``alpha`` is more conservative.
    pfa = learn_pfa_alergia(samples, alpha=0.05)
    pfa.validate()
 
-.. autofunction:: sofic.automata.alergia.learn_pfa_alergia
+.. autofunction:: sofic.automata.learning.alergia.learn_pfa_alergia
 
 Passive learning (PAPNI)
 ========================
 
 PAPNI extends passive inference to visibly pushdown languages. Words over a
-:class:`~sofic.automata.papni.DyckAlphabet` are stack-encoded, a DFA is
+:class:`~sofic.automata.learning.papni.DyckAlphabet` are stack-encoded, a DFA is
 induced over the encoding, and the result is decoded to a
 :class:`~sofic.shifts.sofic_dyck.SoficDyckShift` :cite:`Muskardin2025`:
 
@@ -181,13 +181,13 @@ induced over the encoding, and the result is decoded to a
    shift = learn_sofic_dyck_shift_papni(positive=["()", "(())"], negative=["("], alphabet=alphabet)
 
 For fitting probabilities on the learned topology, see
-:doc:`../generators/stack_inference`.
+:doc:`../inference/stack_cssr`.
 
-.. autoclass:: sofic.automata.papni.DyckAlphabet
+.. autoclass:: sofic.automata.learning.papni.DyckAlphabet
    :members: classify, symbol_alphabet
 
-.. autofunction:: sofic.automata.papni.learn_sofic_dyck_shift_papni
-.. autofunction:: sofic.automata.papni.is_well_matched
-.. autofunction:: sofic.automata.papni.papni_encode
-.. autofunction:: sofic.automata.papni.papni_encode_samples
-.. autofunction:: sofic.automata.papni.sofic_dyck_shift_from_papni_dfa
+.. autofunction:: sofic.automata.learning.papni.learn_sofic_dyck_shift_papni
+.. autofunction:: sofic.automata.learning.papni.is_well_matched
+.. autofunction:: sofic.automata.learning.papni.papni_encode
+.. autofunction:: sofic.automata.learning.papni.papni_encode_samples
+.. autofunction:: sofic.automata.learning.papni.sofic_dyck_shift_from_papni_dfa

docs/automata/observation_table.rst

@@ -1,5 +1,5 @@
 .. observation_table.rst
-.. py:module:: sofic.automata.observation
+.. py:module:: sofic.automata.learning.observation
 
 *****************
 Observation Table
@@ -15,7 +15,7 @@ API
 
 .. autoclass:: ObservationTable
 
-.. autofunction:: sofic.automata.canonical_extraction.observation_to_canonical_rfsa
-.. autofunction:: sofic.automata.canonical_extraction.observation_to_atomaton
-.. autofunction:: sofic.automata.canonical_extraction.observation_to_maximized_prime_atomaton
-.. autofunction:: sofic.automata.canonical_extraction.observation_to_minimal_dfa
+.. autofunction:: sofic.automata.canonical.residual.observation_to_canonical_rfsa
+.. autofunction:: sofic.automata.canonical.residual.observation_to_atomaton
+.. autofunction:: sofic.automata.canonical.residual.observation_to_maximized_prime_atomaton
+.. autofunction:: sofic.automata.canonical.residual.observation_to_minimal_dfa

docs/automata/rfsa.rst

@@ -1,5 +1,5 @@
 .. rfsa.rst
-.. py:module:: sofic.automata.rfsa
+.. py:module:: sofic.automata.canonical.rfsa
 
 ***
 RFSA
@@ -25,7 +25,7 @@ canonical RFSA from queries (:doc:`learning`).
 
 .. code-block:: python
 
-    from sofic.automata.rfsa import CanonicalRFSA
+    from sofic.automata.canonical.rfsa import CanonicalRFSA
 
     rfsa = CanonicalRFSA.from_language(nfa)
     rfsa.validate()               # every state accepts a residual
@@ -38,6 +38,6 @@ API
 .. autoclass:: CanonicalRFSA
    :members: from_language, from_observation_table, dual
 
-.. autofunction:: sofic.automata.canonical_extraction.canonical_rfsa_from_language
-.. autoclass:: sofic.automata.canonical_extraction.ResidualTable
+.. autofunction:: sofic.automata.canonical.residual.canonical_rfsa_from_language
+.. autoclass:: sofic.automata.canonical.residual.ResidualTable
    :members: includes, is_covered, prime_states

docs/automata/vpa.rst

@@ -74,8 +74,8 @@ forms exist for well-matched languages, or once calls are assigned to modules
    The shared modular generalization: a call's target depends only on the call
    symbol.
 
-:func:`~sofic.automata.vpa_constructions.to_single_entry` and
-:func:`~sofic.automata.vpa_constructions.to_multiple_entry` convert any VPA of a
+:func:`~sofic.automata.vpa.operations.to_single_entry` and
+:func:`~sofic.automata.vpa.operations.to_multiple_entry` convert any VPA of a
 well-matched language into these forms (default: one module per call symbol).
 On a call the state resets to the module's entry and the caller is pushed, so
 the automaton forgets its caller; that is why pending calls -- and hence
@@ -114,8 +114,8 @@ API
 .. autoclass:: CanonicalVisiblyPushdownAutomaton
    :members: from_vpa
 
-.. automodule:: sofic.automata.vpa_constructions
+.. automodule:: sofic.automata.vpa.operations
    :members: normalize, determinize, complement, concat, kleene_star, well_matched_summaries, accepted_word,
              has_unmatched_word, to_single_entry, to_multiple_entry
 
-.. autofunction:: sofic.automata.vpa_simulation.recognizes_vpa
+.. autofunction:: sofic.automata.vpa.simulation.recognizes_vpa

docs/generators/epsilon_machine.rst

@@ -87,7 +87,7 @@ structure can differ, because a cycle weight may equal one only by algebraic
 coincidence in the probabilities.
 
 See also :doc:`bidirectional_epsilon_machine`, :doc:`information_anatomy`,
-:doc:`block_convergence`, and :doc:`epsilon_inference` (sample-based reconstruction).
+:doc:`block_convergence`, and :doc:`../inference/cssr` (sample-based reconstruction).
 
 API
 ===

docs/generators/epsilon_transducer.rst

@@ -41,7 +41,7 @@ Minimize a joint-unifilar stochastic transducer to its causal states:
 The channel can also be read off a joint ``(input, output)`` generator with
 :meth:`~EpsilonTransducer.from_joint_generator`, or reconstructed from paired
 sample sequences with :meth:`~EpsilonTransducer.from_paired_sequences` (the
-transCSSR algorithm, :doc:`epsilon_transducer_inference`).
+transCSSR algorithm, :doc:`../inference/transcssr`).
 
 Channel measures
 ================

docs/generators/generators.rst

@@ -50,17 +50,6 @@ Constructions and conversions
    conversions
    lumping
 
-Inference
-=========
-
-.. toctree::
-   :maxdepth: 1
-
-   hmm_inference
-   epsilon_inference
-   epsilon_transducer_inference
-   stack_inference
-
 Advanced
 ========
 

docs/generators/epsilon_inference.rst → docs/inference/cssr.rst

@@ -1,5 +1,5 @@
-.. epsilon_inference.rst
-.. py:module:: sofic.generators.epsilon_inference
+.. cssr.rst
+.. py:module:: sofic.inference.cssr
 
 **************************
 ε-Machine inference
@@ -99,7 +99,7 @@ apply directly.
 After reconstruction, check the result with
 :func:`~sofic.inference.diagnostics.goodness_of_fit` and
 :func:`~sofic.inference.diagnostics.structure_stability`
-(see :doc:`../inference/diagnostics`).
+(see :doc:`diagnostics`).
 
 .. autofunction:: morphs_differ
 
@@ -139,22 +139,22 @@ process). Otherwise the Hankel singular-value gap selects the rank.
        observations, method="spectral", prefix_length=3, rank=2
    )
 
-.. autofunction:: spectral
+.. autofunction:: sofic.inference.spectral.spectral
 
 Unified entry point
 ===================
 
 Use :meth:`~sofic.generators.epsilon_machine.EpsilonMachine.from_sequence` to
 dispatch to CSSR, subtree merging, or spectral reconstruction
-(see :doc:`epsilon_machine`).
+(see :doc:`../generators/epsilon_machine`).
 
 Related inference methods
 =========================
 
-**transCSSR** — input/output ε-transducers; see :doc:`epsilon_transducer_inference`.
+**transCSSR** — input/output ε-transducers; see :doc:`transcssr`.
 
 **Bayesian structural inference** — conjugate Dirichlet–multinomial evidence over
-candidate unifilar topologies :cite:`Strelioff2014`; see :doc:`../inference/epsilon`.
+candidate unifilar topologies :cite:`Strelioff2014`; see :doc:`epsilon`.
 This is not a Gibbs clustering heuristic over history labels.
 
 Subtree merging is the literature reconstruction by morph clustering; a separate
@@ -173,5 +173,5 @@ the causal-state construction used after spectral learning.
 
 **RKHS ε-machines** — continuous-time extension (arXiv:2011.14821).
 
-See also :doc:`epsilon_machine`, :doc:`constructions`, :doc:`hmm_inference`,
-and :doc:`../inference/spectral`.
+See also :doc:`../generators/epsilon_machine`, :doc:`../generators/constructions`, :doc:`hmm`,
+and :doc:`spectral`.

docs/inference/diagnostics.rst

@@ -29,7 +29,7 @@ usually means ``Lmax`` is shorter than the source's synchronization length.
 
 .. code-block:: python
 
-   from sofic.generators.epsilon_inference import cssr
+   from sofic.inference.cssr import cssr
    from sofic.inference.diagnostics import goodness_of_fit
 
    machine = cssr(data, Lmax=1)

docs/inference/hdp_hmm.rst

@@ -60,7 +60,7 @@ The HDP-HMM infers the state count nonparametrically, whereas
 :doc:`model_selection` scores a *fixed* set of candidate orders with information
 criteria and :mod:`sofic.inference.bayesian` compares fixed unifilar topologies
 by exact Dirichlet-multinomial evidence. For point-estimate reconstruction see
-CSSR in :doc:`../generators/epsilon_inference`.
+CSSR in :doc:`cssr`.
 
 API
 ===