Source code for hybrid_aif.distributions.learnable

"""The ``Learnable`` protocol: what a parameter-distribution declaration provides.

A slot holds either a point value or a distribution over its parameters;
``isinstance(decl, Learnable)`` is the capability test, resolved at trace time. Whether a call
advances the posterior, and how fast, is a per-call rate on ``System.learn``, never a field here.

- ``expected_log_params()``: ``E[log params]``, what inference averages over (FPI's digamma
  table); distinct from ``ConditionalCategorical.expected_log(parent_beliefs)``.
- ``point()``: the posterior-mean declaration; its return type is documented per class.
- ``stats(...)`` + ``absorb(stats, lr, decay)``: one tick's sufficient statistic, then its
  (optionally decayed) absorption; ``stats`` signatures are per family.
- ``novelty()``: parameter-info-gain weights (exact ``spm_wnorm``, better-when-larger).
- ``sample(key)``: a parameter draw from the posterior, for ``as_env(params, param_key=...)``.

Design: docs/design/parameter-learning.md D3 (the protocol)
"""

from typing import Protocol, runtime_checkable

from jax import Array


[docs] @runtime_checkable class Learnable(Protocol): """Structural capability protocol (see module docstring), satisfied by method presence. New conjugate families join by implementing the members; there is no registry and no flag. """ def expected_log_params(self) -> Array: ... def point(self): ... # per-slot return type; documented on each class def stats(self, *args, **kwargs) -> Array: ... # per-family signature def absorb(self, stats: Array, lr: float | Array = 1.0, decay: float | Array = 1.0): ... def novelty(self) -> Array: ... def sample(self, key: Array): ...