marmo 0.1.0__py3-none-any.whl

markovlib/__init__.py

@@ -0,0 +1,58 @@
+"""markovlib — Markov-like processes as one recursion parameterized by a belief algebra + semiring.
+
+Public surface (vertical slice): the model (:class:`DiscreteChain`), the engine
+(:class:`ExactChain`), the semirings (:class:`SumProduct` / :class:`MaxPlus`), the decidable dispatch
+(:func:`resolve_engine` → :class:`Exact` / :class:`Approximate` / :class:`Intractable`), and the uniform
+queries (:func:`smooth` / :func:`decode` / :func:`loglik`).
+"""
+
+from __future__ import annotations
+
+from markovlib.belief import Belief, Categorical, GaussianBelief
+from markovlib.dispatch import resolve_engine
+from markovlib.duration import DurationModel, NegBinomDuration
+from markovlib.engines.exact_chain import ExactChain, ExpectedStats, SmoothResult
+from markovlib.engines.gaussian import FilterResult, GaussianChain, GaussianSmoothResult
+from markovlib.engines.particle import ParticleFilter, ParticleResult
+from markovlib.engines.segmental import SegmentalChain
+from markovlib.learn import FitResult, fit
+from markovlib.model import DiscreteChain, LinearGaussian, SemiMarkovChain, StateSpaceModel
+from markovlib.query import decode, filter, loglik, particle_filter, smooth
+from markovlib.resolution import Approximate, EngineResolution, Exact, Intractable
+from markovlib.semiring import MaxPlus, Semiring, SumProduct
+
+__all__ = [
+    "Belief",
+    "Categorical",
+    "GaussianBelief",
+    "DiscreteChain",
+    "SemiMarkovChain",
+    "LinearGaussian",
+    "StateSpaceModel",
+    "DurationModel",
+    "NegBinomDuration",
+    "ExactChain",
+    "SegmentalChain",
+    "GaussianChain",
+    "ParticleFilter",
+    "SmoothResult",
+    "ExpectedStats",
+    "FilterResult",
+    "GaussianSmoothResult",
+    "ParticleResult",
+    "FitResult",
+    "fit",
+    "Semiring",
+    "SumProduct",
+    "MaxPlus",
+    "Exact",
+    "Approximate",
+    "Intractable",
+    "EngineResolution",
+    "resolve_engine",
+    "smooth",
+    "decode",
+    "loglik",
+    "filter",
+    "particle_filter",
+]

markovlib/belief.py

@@ -0,0 +1,109 @@
+"""The belief algebra — the message representation the one recursion is generic over.
+
+A :class:`Belief` is a distribution-shaped message. The forward recursion asks only two things of it:
+``combine`` (``⊗`` — fold in a local factor / emission) and ``log_mass`` (for the likelihood and for
+normalization). The *push-forward* through the dynamics is supplied to the recursion separately as a
+``predict`` callable, so the belief type stays ignorant of the transition. Swapping the belief —
+:class:`Categorical` (log-vector) now; Gaussian (moment / information form) and particle (samples +
+weights) later — turns the *same* recursion into forward–backward, Kalman/RTS, or a particle filter,
+exactly as swapping the semiring turns posteriors into MAP. Belief × semiring are the two orthogonal
+axes the whole library rides on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, Self
+
+import numpy as np
+import numpy.typing as npt
+from scipy.special import logsumexp
+
+Float = npt.NDArray[np.float64]
+
+
+class Belief(Protocol):
+    """A distribution-shaped message: fold in a like factor, normalize, and report its log-mass."""
+
+    def combine(self, factor: Self, /) -> Self:
+        """``⊗`` — fold in another belief / local factor (log-domain for :class:`Categorical`)."""
+        ...
+
+    def log_mass(self) -> float:
+        """The log of the total (unnormalized) mass — this step's contribution to the likelihood."""
+        ...
+
+    def normalized(self) -> Self:
+        """This belief rescaled to unit mass."""
+        ...
+
+
+@dataclass(frozen=True)
+class Categorical:
+    """A categorical belief: an (unnormalized) log-probability vector over ``S`` states."""
+
+    log_p: Float
+
+    def combine(self, factor: Categorical, /) -> Categorical:
+        """Pointwise ``⊗`` — add the log-vectors (multiply the unnormalized densities)."""
+        return Categorical(self.log_p + factor.log_p)
+
+    def log_mass(self) -> float:
+        """``logsumexp`` of the log-vector — the total unnormalized mass."""
+        return float(logsumexp(self.log_p))
+
+    def normalized(self) -> Categorical:
+        """The belief rescaled to a proper distribution (subtract the log-mass)."""
+        return Categorical(self.log_p - self.log_mass())
+
+    def probs(self) -> Float:
+        """The normalized probability vector."""
+        return np.exp(self.normalized().log_p)
+
+    def mode(self) -> int:
+        """The most probable state index (MAP marginal)."""
+        return int(np.argmax(self.log_p))
+
+
+@dataclass(frozen=True)
+class GaussianBelief:
+    """A Gaussian message in information (canonical) form ``φ(x) = exp(-½ xᵀΛx + ηᵀx + g)``.
+
+    ``eta`` is the information vector ``η``, ``precision`` is ``Λ`` (symmetric positive-definite),
+    ``log_scale`` is ``g``. The product of two canonical potentials just *adds* ``(η, Λ, g)`` — the
+    Gaussian analog of :class:`Categorical`'s log-add — so :meth:`combine` is elementwise addition. And
+    ``log_mass`` is ``log ∫ φ``: under the filtering recursion the running message is
+    ``φ_t(x_t) = p(x_t, y_{0:t})``, so ``log_mass`` is ``log p(y_{0:t})`` and the final message's
+    ``log_mass`` is the data log-likelihood — exactly parallel to Categorical.
+    """
+
+    eta: Float
+    precision: Float
+    log_scale: float = 0.0
+
+    def combine(self, factor: GaussianBelief, /) -> GaussianBelief:
+        """``⊗`` — multiply the canonical potentials (add information vectors, precisions, and scales)."""
+        return GaussianBelief(
+            self.eta + factor.eta, self.precision + factor.precision, self.log_scale + factor.log_scale
+        )
+
+    def log_mass(self) -> float:
+        """``log ∫ φ(x) dx = g + d/2·log 2π − ½·log|Λ| + ½·ηᵀΛ⁻¹η``."""
+        dim = int(self.eta.shape[0])
+        _, log_det = np.linalg.slogdet(self.precision)
+        quad = float(self.eta @ np.linalg.solve(self.precision, self.eta))
+        return float(self.log_scale + 0.5 * dim * np.log(2.0 * np.pi) - 0.5 * float(log_det) + 0.5 * quad)
+
+    def normalized(self) -> GaussianBelief:
+        """The belief rescaled to unit mass (a proper density: ``log_mass == 0``)."""
+        return GaussianBelief(self.eta, self.precision, self.log_scale - self.log_mass())
+
+    def mean(self) -> Float:
+        """The distribution mean ``μ = Λ⁻¹η``."""
+        mean: Float = np.linalg.solve(self.precision, self.eta)
+        return mean
+
+    def covariance(self) -> Float:
+        """The distribution covariance ``Σ = Λ⁻¹``."""
+        cov: Float = np.linalg.inv(self.precision)
+        return cov

markovlib/dispatch.py

@@ -0,0 +1,33 @@
+"""``resolve_engine`` — markovlib's ``decide()``: which engine resolves a query, and how exactly.
+
+The deliberate analog of fungeom's decidable dispatch: given a model and a query, return *evidence*
+(:data:`~markovlib.resolution.EngineResolution`) naming the engine and its exactness, never a silent
+best-effort. A :class:`~markovlib.model.DiscreteChain` resolves ``smooth`` / ``decode`` / ``loglik``
+exactly; a :class:`~markovlib.model.SemiMarkovChain` resolves ``decode`` exactly; a
+:class:`~markovlib.model.LinearGaussian` resolves ``filter`` exactly (the Kalman filter). New engines
+register here, each declaring ``Exact`` or ``Approximate`` for the queries they resolve.
+"""
+
+from __future__ import annotations
+
+from markovlib.engines.exact_chain import ExactChain
+from markovlib.engines.gaussian import GaussianChain
+from markovlib.engines.particle import ParticleFilter
+from markovlib.engines.segmental import SegmentalChain
+from markovlib.model import DiscreteChain, LinearGaussian, SemiMarkovChain, StateSpaceModel
+from markovlib.resolution import Approximate, EngineResolution, Exact, Intractable
+
+_CHAIN_QUERIES = frozenset({"smooth", "decode", "loglik"})
+
+
+def resolve_engine(model: object, query: str) -> EngineResolution:
+    """Return evidence for which engine resolves ``query`` on ``model``, and whether exactly."""
+    if isinstance(model, DiscreteChain) and query in _CHAIN_QUERIES:
+        return Exact(ExactChain())
+    if isinstance(model, SemiMarkovChain) and query in {"decode", "smooth"}:
+        return Exact(SegmentalChain())
+    if isinstance(model, LinearGaussian) and query in {"filter", "smooth"}:
+        return Exact(GaussianChain())
+    if isinstance(model, StateSpaceModel) and query == "filter":
+        return Approximate(ParticleFilter(), "bootstrap particle filter", "O(1/sqrt(N)) Monte Carlo")
+    return Intractable(f"no engine for {type(model).__name__} / query={query!r}")

markovlib/duration.py

@@ -0,0 +1,69 @@
+"""Duration models for semi-Markov chains — explicit dwell-time distributions.
+
+In a plain Markov chain the time spent in a state is *implicitly* geometric (set by the self-transition
+probability). A semi-Markov chain instead gives each state an **explicit** dwell distribution and forbids
+self-transitions — persistence is owned by the duration, not the transition. :class:`NegBinomDuration`
+is the shifted negative-binomial dwell (a mean and a dispersion); its ``concentration → 1`` limit is the
+geometric dwell, so a semi-Markov chain with geometric durations degrades exactly to a plain HMM.
+
+Both the point mass (:meth:`~NegBinomDuration.log_pmf`) and the right tail
+(:meth:`~NegBinomDuration.log_survival`, ``log P(dwell ≥ d)``) are exposed: the segmental decoder scores
+a naturally-ended segment by the pmf and a segment that hits the duration cap by the survival (the
+standard explicit-duration **right-censoring**, which lets a state persist past the cap).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from scipy.stats import nbinom
+
+
+class DurationModel(Protocol):
+    """A dwell-time distribution over integer durations ``d ≥ 1``."""
+
+    def log_pmf(self, d: int) -> float:
+        """``log P(dwell = d)`` for ``d ≥ 1``."""
+        ...
+
+    def log_survival(self, d: int) -> float:
+        """``log P(dwell ≥ d)`` — the right-censored mass a capped segment scores."""
+        ...
+
+
+@dataclass(frozen=True)
+class NegBinomDuration:
+    """Shifted negative-binomial dwell over ``d ≥ 1`` with given ``mean`` (> 1) and ``concentration`` (> 0).
+
+    Parameterized so ``E[d] = mean`` exactly: with ``k = d - 1 ~ NB(r = concentration, p)`` and
+    ``p = r / (r + mean - 1)``. The ``concentration → 1`` limit is the geometric dwell
+    ``P(d) = (1 - q)^{d-1} q`` with ``q = 1 / mean`` (a plain HMM's implicit dwell); larger
+    ``concentration`` concentrates the mass around the mean. Backed by :data:`scipy.stats.nbinom`.
+    """
+
+    mean: float
+    concentration: float
+
+    def __post_init__(self) -> None:
+        if self.mean <= 1.0:
+            raise ValueError(f"mean dwell must be > 1 (got {self.mean})")
+        if self.concentration <= 0.0:
+            raise ValueError(f"concentration must be > 0 (got {self.concentration})")
+
+    def _params(self) -> tuple[float, float]:
+        r = self.concentration
+        p = r / (r + self.mean - 1.0)
+        return r, p
+
+    def log_pmf(self, d: int) -> float:
+        """``log P(dwell = d)`` — the shifted negative-binomial log-pmf at integer ``d ≥ 1``."""
+        if d < 1:
+            raise ValueError(f"duration must be >= 1 (got {d})")
+        r, p = self._params()
+        return float(nbinom.logpmf(d - 1, r, p))
+
+    def log_survival(self, d: int) -> float:
+        """``log P(dwell ≥ d)``. Since ``d = k + 1``, ``P(d ≥ D) = P(k > D - 2) = nbinom.sf(D - 2)``."""
+        r, p = self._params()
+        return float(nbinom.logsf(d - 2, r, p))

markovlib/engines/__init__.py

@@ -0,0 +1 @@
+"""Inference engines — each a concrete resolver of one or more queries over a model."""

markovlib/engines/exact_chain.py

@@ -0,0 +1,96 @@
+"""``ExactChain`` — exact inference for a finite discrete chain.
+
+The reference engine: for a finite-state chain every query (filter / smooth / decode / loglik) and the
+EM E-step (:meth:`ExactChain.expected_stats`) are *exact*, computed by the belief-generic forward
+recursion plus the categorical second passes in :mod:`markovlib.engines.recursion`. Being exact, it is
+also the **reference** future fast/approximate engines are tested against (validated against brute-force
+path enumeration in the tests).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import numpy.typing as npt
+from scipy.special import logsumexp
+
+from markovlib.belief import Categorical
+from markovlib.engines.recursion import backward_messages, categorical_predict, forward, viterbi
+from markovlib.model import DiscreteChain
+from markovlib.semiring import SumProduct
+
+Float = npt.NDArray[np.float64]
+
+
+@dataclass(frozen=True)
+class SmoothResult:
+    """Posterior marginals ``gamma`` ``(T, S)`` (rows sum to 1) and the data log-likelihood."""
+
+    gamma: Float
+    loglik: float
+
+
+@dataclass(frozen=True)
+class ExpectedStats:
+    """The EM E-step's expected sufficient statistics.
+
+    ``gamma`` ``(T, S)`` are the state marginals ``P(state_t = s | obs)``; ``xi`` ``(T-1, S, S)`` are the
+    pairwise marginals ``P(state_t = i, state_{t+1} = j | obs)`` — together they are everything the
+    initial/transition M-step needs. ``loglik`` is the observed-data log-likelihood at these parameters.
+    """
+
+    gamma: Float
+    xi: Float
+    loglik: float
+
+
+class ExactChain:
+    """Exact filter / smooth / decode / loglik + EM E-step for a :class:`~markovlib.model.DiscreteChain`."""
+
+    def _forward(self, model: DiscreteChain, log_emissions: Float) -> list[Categorical]:
+        """The sum-product forward beliefs ``α`` — the belief-generic recursion at categorical instance."""
+        factors = [Categorical(row) for row in log_emissions]
+        predict = categorical_predict(model.log_trans, SumProduct())
+        return forward(Categorical(model.log_init), predict, factors)
+
+    def _alpha_beta(self, model: DiscreteChain, log_emissions: Float) -> tuple[Float, Float, float]:
+        """The log forward ``α``, the log backward ``β``, and the data log-likelihood."""
+        alpha = self._forward(model, log_emissions)
+        log_alpha = np.stack([belief.log_p for belief in alpha])
+        beta = backward_messages(model.log_trans, log_emissions)
+        loglik = float(logsumexp(log_alpha[-1]))
+        return log_alpha, beta, loglik
+
+    @staticmethod
+    def _gamma(log_alpha: Float, beta: Float) -> Float:
+        """Posterior state marginals ``γ[t] = normalize(α[t] + β[t])``."""
+        unnorm = log_alpha + beta
+        gamma: Float = np.exp(unnorm - logsumexp(unnorm, axis=1, keepdims=True))
+        return gamma
+
+    def smooth(self, model: DiscreteChain, log_emissions: Float) -> SmoothResult:
+        """Forward–backward: posterior marginals + log-likelihood (sum-product)."""
+        log_alpha, beta, loglik = self._alpha_beta(model, log_emissions)
+        return SmoothResult(gamma=self._gamma(log_alpha, beta), loglik=loglik)
+
+    def loglik(self, model: DiscreteChain, log_emissions: Float) -> float:
+        """The data log-likelihood ``log p(observations)`` (forward pass only)."""
+        return self._forward(model, log_emissions)[-1].log_mass()
+
+    def expected_stats(self, model: DiscreteChain, log_emissions: Float) -> ExpectedStats:
+        """The EM E-step: state marginals ``γ``, pairwise marginals ``ξ``, and the log-likelihood.
+
+        ``ξ[t, i, j] = normalize( α[t, i] + log A[i, j] + log b_{t+1}(j) + β[t+1, j] )`` (normalized by the
+        log-likelihood). It marginalizes to ``γ`` (``Σ_j ξ[t, i, j] = γ[t, i]``) and sums to 1 per ``t``.
+        """
+        log_alpha, beta, loglik = self._alpha_beta(model, log_emissions)
+        gamma = self._gamma(log_alpha, beta)
+        transition = model.log_trans[None, :, :] if model.log_trans.ndim == 2 else model.log_trans
+        log_xi = log_alpha[:-1, :, None] + transition + (log_emissions[1:] + beta[1:])[:, None, :] - loglik
+        return ExpectedStats(gamma=gamma, xi=np.exp(log_xi), loglik=loglik)
+
+    def decode(self, model: DiscreteChain, log_emissions: Float) -> npt.NDArray[np.intp]:
+        """The single most likely state path (Viterbi / MAP, max-plus)."""
+        path, _ = viterbi(model.log_init, model.log_trans, log_emissions)
+        return path

markovlib/engines/gaussian.py

@@ -0,0 +1,114 @@
+"""``GaussianChain`` — the Kalman filter, as the *same* forward recursion with a Gaussian belief.
+
+This is the payoff of the belief abstraction: :func:`~markovlib.engines.recursion.forward` is reused
+verbatim — only the belief type changes from :class:`~markovlib.belief.Categorical` to
+:class:`~markovlib.belief.GaussianBelief`. The observation at each step enters as a fixed Gaussian
+*factor* (the likelihood ``N(y_t | H x, R)`` written as a canonical potential in ``x``), ``combine`` is
+the canonical-form product, and the transition push-forward is the linear-Gaussian prediction. The
+running message is the unnormalized filtering density ``p(x_t, y_{0:t})``; its mean/covariance are the
+Kalman filtered estimate and its ``log_mass`` accumulates the data log-likelihood — so the categorical
+HMM and the Kalman filter are literally two instantiations of one recursion.
+
+The RTS smoother (the Gaussian backward pass) and a particle filter (a sibling engine needing reified
+randomness) are deliberate next steps.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import numpy as np
+import numpy.typing as npt
+
+from markovlib.belief import GaussianBelief
+from markovlib.engines.recursion import forward
+from markovlib.model import LinearGaussian
+
+Float = npt.NDArray[np.float64]
+
+
+@dataclass(frozen=True)
+class FilterResult:
+    """Kalman filtered estimates: per-step ``means`` ``(T, D)``, ``covariances`` ``(T, D, D)``, and loglik."""
+
+    means: Float
+    covariances: Float
+    loglik: float
+
+
+@dataclass(frozen=True)
+class GaussianSmoothResult:
+    """RTS-smoothed estimates ``p(x_t | y_{0:T-1})``: per-step ``means``, ``covariances``, and the data loglik."""
+
+    means: Float
+    covariances: Float
+    loglik: float
+
+
+def _observation_factor(model: LinearGaussian, y: Float) -> GaussianBelief:
+    """The likelihood ``N(y | H x, R)`` as a canonical potential in ``x`` (a fixed per-step factor)."""
+    obs_precision = np.linalg.inv(model.obs_noise)
+    transposed = model.observation.T @ obs_precision
+    precision = transposed @ model.observation
+    eta = transposed @ y
+    dim_obs = int(y.shape[0])
+    _, log_det_r = np.linalg.slogdet(model.obs_noise)
+    log_scale = -0.5 * (dim_obs * np.log(2.0 * np.pi) + float(log_det_r)) - 0.5 * float(y @ obs_precision @ y)
+    return GaussianBelief(eta, precision, log_scale)
+
+
+def _prior_factor(model: LinearGaussian) -> GaussianBelief:
+    """The initial prior ``N(m0, P0)`` as a normalized canonical potential."""
+    precision = np.linalg.inv(model.init_cov)
+    eta = precision @ model.init_mean
+    return GaussianBelief(eta, precision, 0.0).normalized()
+
+
+def gaussian_predict(transition: Float, process_noise: Float) -> Callable[[GaussianBelief, int], GaussianBelief]:
+    """The linear-Gaussian push-forward ``μ ↦ Aμ``, ``Σ ↦ AΣAᵀ + Q`` (mass-preserving)."""
+
+    def predict(belief: GaussianBelief, step: int) -> GaussianBelief:
+        log_mass = belief.log_mass()  # prediction is a convolution — it preserves the total mass
+        mean = transition @ belief.mean()
+        cov = transition @ belief.covariance() @ transition.T + process_noise
+        precision = np.linalg.inv(cov)
+        eta = precision @ mean
+        unscaled = GaussianBelief(eta, precision, 0.0)
+        return GaussianBelief(eta, precision, log_mass - unscaled.log_mass())
+
+    return predict
+
+
+class GaussianChain:
+    """Exact Kalman filtering and RTS smoothing for a :class:`~markovlib.model.LinearGaussian` model."""
+
+    def _filtered_beliefs(self, model: LinearGaussian, observations: Float) -> list[GaussianBelief]:
+        """The filtered messages — the shared forward recursion with a Gaussian belief."""
+        prior = _prior_factor(model)
+        factors = [_observation_factor(model, y) for y in observations]
+        predict = gaussian_predict(model.transition, model.process_noise)
+        return forward(prior, predict, factors)
+
+    def filter(self, model: LinearGaussian, observations: Float) -> FilterResult:
+        """The filtered ``p(x_t | y_{0:t})`` mean/covariance per step + the data log-likelihood."""
+        beliefs = self._filtered_beliefs(model, observations)
+        means = np.stack([belief.mean() for belief in beliefs])
+        covariances = np.stack([belief.covariance() for belief in beliefs])
+        return FilterResult(means=means, covariances=covariances, loglik=beliefs[-1].log_mass())
+
+    def smooth(self, model: LinearGaussian, observations: Float) -> GaussianSmoothResult:
+        """The RTS-smoothed ``p(x_t | y_{0:T-1})`` mean/covariance per step (filter forward + RTS backward)."""
+        beliefs = self._filtered_beliefs(model, observations)
+        filtered_means = [belief.mean() for belief in beliefs]
+        filtered_covs = [belief.covariance() for belief in beliefs]
+        transition, process_noise = model.transition, model.process_noise
+        smoothed_means = list(filtered_means)  # the last step is already smoothed (= filtered)
+        smoothed_covs = list(filtered_covs)
+        for t in range(len(beliefs) - 2, -1, -1):
+            predicted_mean = transition @ filtered_means[t]
+            predicted_cov = transition @ filtered_covs[t] @ transition.T + process_noise
+            gain = filtered_covs[t] @ transition.T @ np.linalg.inv(predicted_cov)
+            smoothed_means[t] = filtered_means[t] + gain @ (smoothed_means[t + 1] - predicted_mean)
+            smoothed_covs[t] = filtered_covs[t] + gain @ (smoothed_covs[t + 1] - predicted_cov) @ gain.T
+        return GaussianSmoothResult(np.stack(smoothed_means), np.stack(smoothed_covs), beliefs[-1].log_mass())

markovlib/engines/particle.py

@@ -0,0 +1,84 @@
+"""``ParticleFilter`` — a bootstrap (sequential-importance-resampling) filter, a *sibling* engine.
+
+Unlike the categorical/Gaussian filters, this does **not** use the shared
+:func:`~markovlib.engines.recursion.forward`: the per-step evidence is a *state-dependent* reweighting
+(the likelihood evaluated at the particle locations), not a fixed factor to ``combine``, and the
+prediction step *samples* the transition. So it stands alongside the segmental DP as an engine that does
+not fit the two-sweep mold — and it is the library's first **approximate** engine (Monte Carlo,
+``O(1/√N)``), which is why :func:`~markovlib.dispatch.resolve_engine` reports it as ``Approximate``.
+
+Randomness is **reified**: the whole filter is a deterministic function of its ``seed`` (and ``model``,
+``observations``, ``n_particles``) — the same "reify the seed as an explicit input" discipline that keeps
+the engine referentially transparent. Resampling (systematic, triggered when the effective sample size
+falls below ``resample_threshold · N``) and the marginal-likelihood estimate are the standard SIR forms.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import numpy.typing as npt
+from scipy.special import logsumexp
+
+from markovlib.model import StateSpaceModel
+
+Float = npt.NDArray[np.float64]
+Int = npt.NDArray[np.intp]
+
+
+@dataclass(frozen=True)
+class ParticleResult:
+    """Filtered (weighted particle) ``means`` ``(T, D)``, the marginal-likelihood estimate, and per-step ESS."""
+
+    means: Float
+    loglik: float
+    ess: Float
+
+
+def _systematic_resample(weights: Float, rng: np.random.Generator) -> Int:
+    """Systematic resampling: one uniform draw fixes ``N`` evenly-spaced positions on the CDF."""
+    n = weights.shape[0]
+    positions = (float(rng.random()) + np.arange(n)) / n
+    cumulative = np.cumsum(weights)
+    cumulative[-1] = 1.0  # guard against floating-point drift past the last bin
+    indices: Int = np.searchsorted(cumulative, positions).astype(np.intp)
+    return indices
+
+
+class ParticleFilter:
+    """A bootstrap particle filter for a :class:`~markovlib.model.StateSpaceModel`."""
+
+    def filter(
+        self,
+        model: StateSpaceModel,
+        observations: Float,
+        *,
+        n_particles: int,
+        seed: int,
+        resample_threshold: float = 0.5,
+    ) -> ParticleResult:
+        """Filter ``observations`` with ``n_particles`` particles; deterministic given ``seed``."""
+        rng = np.random.default_rng(seed)
+        particles = np.asarray(model.sample_prior(rng, n_particles), dtype=np.float64)
+        log_weights = np.full(n_particles, -np.log(n_particles))
+        means: list[Float] = []
+        ess_per_step: list[float] = []
+        loglik = 0.0
+
+        for step, y in enumerate(observations):
+            if step > 0:
+                particles = np.asarray(model.propagate(rng, particles), dtype=np.float64)
+            log_weights = log_weights + np.asarray(model.log_likelihood(y, particles), dtype=np.float64)
+            increment = float(logsumexp(log_weights))  # log Σ Wᵢ·p(yₜ|xᵢ) — the marginal-likelihood step
+            loglik += increment
+            log_weights = log_weights - increment  # renormalize (Σ exp = 1)
+            weights = np.exp(log_weights)
+            ess = float(1.0 / np.sum(weights**2))
+            means.append(weights @ particles)
+            ess_per_step.append(ess)
+            if ess < resample_threshold * n_particles:
+                particles = particles[_systematic_resample(weights, rng)]
+                log_weights = np.full(n_particles, -np.log(n_particles))
+
+        return ParticleResult(means=np.array(means), loglik=loglik, ess=np.array(ess_per_step))

markovlib/engines/recursion.py

@@ -0,0 +1,94 @@
+"""The one forward recursion (belief-generic), plus the categorical second passes.
+
+:func:`forward` is *the* load-bearing primitive: a single recursion generic over the belief type and a
+per-step ``predict`` push-forward, touching the belief only through :meth:`~markovlib.belief.Belief.combine`.
+The categorical chain supplies :func:`categorical_predict` (a semiring matrix-vector push): with
+:class:`~markovlib.semiring.SumProduct` the messages are the forward ``α`` of forward–backward; with
+:class:`~markovlib.semiring.MaxPlus` they are the Viterbi score table ``δ``. The sum-product smoother adds
+:func:`backward_messages`; the max-plus decoder adds argmax backpointers + a backtrace (:func:`viterbi`).
+
+Transitions may be **homogeneous** (a single ``(S, S)`` ``log_trans``) or **time-varying** (a
+``(T-1, S, S)`` tensor, where ``log_trans[k]`` is the step-``k`` → step-``k+1`` transition). Every pass
+dispatches on ``log_trans.ndim``, so the gated/inhomogeneous case (a contact-style per-frame transition)
+runs the same code as the plain chain.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+import numpy as np
+import numpy.typing as npt
+from scipy.special import logsumexp
+
+from markovlib.belief import Belief, Categorical
+from markovlib.semiring import Semiring
+
+Float = npt.NDArray[np.float64]
+Int = npt.NDArray[np.intp]
+
+
+def forward[B: Belief](initial: B, predict: Callable[[B, int], B], factors: Sequence[B]) -> list[B]:
+    """The forward recursion ``msg[t] = predict(msg[t-1], t) ⊗ factor[t]`` (``msg[0] = initial ⊗ factor[0]``).
+
+    Generic over the belief type ``B``: it touches the belief only through ``combine`` and the supplied
+    ``predict`` push-forward (given the previous belief and the target step ``t``), so categorical /
+    Gaussian / particle beliefs — homogeneous or time-varying — all run this one loop.
+    """
+    messages = [initial.combine(factors[0])]
+    for t in range(1, len(factors)):
+        messages.append(predict(messages[t - 1], t).combine(factors[t]))
+    return messages
+
+
+def categorical_predict(log_trans: Float, semiring: Semiring) -> Callable[[Categorical, int], Categorical]:
+    """The chain push-forward for categorical beliefs: ``b'[j] = ⊕_i ( b[i] ⊗ trans[i, j] )``.
+
+    ``⊗`` is ``+`` (log domain); ``⊕`` is ``semiring.reduce``. ``log_trans`` is ``(S, S)`` (homogeneous)
+    or ``(T-1, S, S)`` (time-varying); entering step ``t`` uses the step-``(t-1)`` → step-``t`` transition.
+    """
+    homogeneous = log_trans.ndim == 2
+
+    def predict(belief: Categorical, step: int) -> Categorical:
+        transition = log_trans if homogeneous else log_trans[step - 1]
+        return Categorical(semiring.reduce(belief.log_p[:, None] + transition, axis=0))
+
+    return predict
+
+
+def backward_messages(log_trans: Float, log_em: Float) -> Float:
+    """The sum-product backward pass ``β[t, i] = logsumexp_j ( trans_t[i, j] + em[t+1, j] + β[t+1, j] )``.
+
+    ``trans_t`` is the step-``t`` → step-``t+1`` transition (``log_trans`` itself if homogeneous, else
+    ``log_trans[t]``).
+    """
+    n_steps, n_states = log_em.shape
+    homogeneous = log_trans.ndim == 2
+    beta = np.zeros((n_steps, n_states), dtype=np.float64)
+    for t in range(n_steps - 2, -1, -1):
+        transition = log_trans if homogeneous else log_trans[t]
+        beta[t] = logsumexp(transition + (log_em[t + 1] + beta[t + 1])[None, :], axis=1)
+    return beta
+
+
+def viterbi(log_init: Float, log_trans: Float, log_em: Float) -> tuple[Int, float]:
+    """Max-plus forward with argmax backpointers + backtrace → ``(map_path, best_logscore)``.
+
+    Shares the recursion *shape* of :func:`forward` (semiring = MaxPlus) but additionally records, at each
+    step, which predecessor achieved the max. Supports homogeneous and time-varying ``log_trans``.
+    """
+    n_steps, n_states = log_em.shape
+    homogeneous = log_trans.ndim == 2
+    delta = np.empty((n_steps, n_states), dtype=np.float64)
+    psi = np.empty((n_steps, n_states), dtype=np.intp)
+    delta[0] = log_init + log_em[0]
+    for t in range(1, n_steps):
+        transition = log_trans if homogeneous else log_trans[t - 1]
+        scores = delta[t - 1][:, None] + transition
+        psi[t] = np.argmax(scores, axis=0)
+        delta[t] = log_em[t] + np.max(scores, axis=0)
+    path = np.empty(n_steps, dtype=np.intp)
+    path[-1] = np.intp(np.argmax(delta[-1]))
+    for t in range(n_steps - 2, -1, -1):
+        path[t] = psi[t + 1, path[t + 1]]
+    return path, float(delta[-1].max())