"""The planner seam: context, protocol, and registry.
A System resolves its planner by name through the registry here, so it holds
only a string and stays a serializable pytree. A :class:`PlannerContext` is what
it offers a planner for one call: jit-traceable closures over the params plus
static action-space structure. It is built per call and never stored.
Design: docs/design/system.md "Planning"
"""
from collections.abc import Callable
from typing import Any, Literal, NamedTuple, Protocol, TypeAlias
from jax import Array
from hybrid_aif.controls import FLOAT, LEVEL, ControlLayout, ControlTable
from hybrid_aif.distributions import Categorical
from hybrid_aif.objectives.base import TermTree
Beliefs: TypeAlias = Any
"""Opaque belief pytree threaded through a planner's scan.
Planners never introspect beliefs; the System's closures define their meaning.
"""
TransitionFn = Callable[[Beliefs, Array], Beliefs]
StepTermsFn = Callable[[Beliefs, Array, Array], TermTree]
TerminalTermsFn = Callable[[Beliefs], TermTree]
BranchFn = Callable[[Beliefs], tuple[Array, Beliefs]]
UseBound = Literal["midpoint", "lower", "upper"]
[docs]
class PlannerContext(NamedTuple):
"""Everything a System offers a planner for a single ``infer_policies`` call.
The posterior is ``q_pi ∝ softmax(-gamma * G + policy_prior)``. An ``action`` is an int32
``(K,)`` vector, one level per control node in node order, unless ``continuous_controls`` is
set: then every node is continuous, the step is the float ``(action_dim,)`` flat vector, its
box ``continuous_controls.bounds``, and every level count is ``1``. A space mixing discrete
and continuous nodes has no flat form: the planner ``"mixed"`` searches it and the other
built-in planners refuse it (:func:`refuse_mixed`). The properties ``num_controls`` and
``controlled`` read the same space in the form :func:`enumerate_policies` takes, so
``enumerate_policies(ctx.num_controls, ctx.policy_len, ctx.controlled)`` is the grid.
"""
#: ``transition_fn(qs, action) -> qs``: pushes beliefs through one control step.
transition_fn: TransitionFn
#: ``step_terms_fn(qs, action, t) -> TermTree``: scores post-transition beliefs.
step_terms_fn: StepTermsFn
#: ``terminal_terms_fn(qs_final) -> TermTree``, or ``None``: scores the horizon end.
terminal_terms_fn: TerminalTermsFn | None
#: The System's :class:`~hybrid_aif.controls.ControlTable`.
controls: ControlTable
#: Each control node's level count (``1`` for every node under ``continuous_controls``).
levels: tuple[int, ...]
#: The horizon the planner plans to.
policy_len: int
#: The policy precision.
gamma: float
#: The prior over policies (``SystemParams.policy_prior``).
policy_prior: Array | Categorical | object | None
#: The beliefs the plan starts from.
init_beliefs: Beliefs
#: The flat layout of an all-continuous control space, or ``None``.
continuous_controls: ControlLayout | None = None
#: A PRNG key; ``None`` except for planners registered with ``needs_key=True``.
key: Array | None = None
#: ``habit_fn(beliefs, key) -> control step``: set exactly when ``policy_prior`` is a policy
#: module.
habit_fn: Callable[[Beliefs, Array], Array] | None = None
#: ``branch_fn(beliefs) -> (p, beliefs_after)``: set exactly when the System declares
#: ``branch_on``; ``p`` has shape ``(n,)`` over the joint outcomes and ``beliefs_after`` a
#: leading ``(n,)`` axis.
branch_fn: BranchFn | None = None
#: Each control node's kind.
kinds: tuple[str, ...] = ()
#: Each control node's level count (a discrete node) or width (a continuous one).
sizes: tuple[int, ...] = ()
#: Each continuous node's :class:`~hybrid_aif.controls.Box` (``None`` for a discrete node).
boxes: tuple[object, ...] = ()
#: Set when the caller passed a per-step ``legal=`` to a planner registered with
#: ``legal_depth=True``: a bool ``(L, A)`` over the ``A`` first-step actions
#: (``enumerate_policies(num_controls, 1, controlled)[:, 0]``), true where that action is
#: legal at that depth; ``L`` is ``policy_len`` for a mask given per step and 1 for a mask on
#: the first step alone.
legal_steps: Array | None = None
@property
def num_controls(self) -> tuple[int, ...]:
"""Each policy column's level count (one column per control node)."""
return self.levels
@property
def controlled(self) -> tuple[bool, ...]:
"""Every policy column is planned over."""
return (True,) * len(self.levels)
def refuse_mixed(ctx: PlannerContext, planner: str) -> None:
"""Raise, with a sentence, when ``ctx``'s control space mixes discrete and continuous
nodes: the built-in planners other than ``"mixed"`` search one kind of space. The sentence
from the ``"gradient"`` and ``"cem"`` planners names ``"mixed"``."""
if LEVEL in ctx.kinds and FLOAT in ctx.kinds:
names = ctx.controls.control_names
discrete = [n for n, k in zip(names, ctx.kinds, strict=True) if k == LEVEL]
continuous = [n for n, k in zip(names, ctx.kinds, strict=True) if k == FLOAT]
lead = (
f"the {planner!r} planner was asked to search a space mixing discrete control nodes "
f"{discrete} and continuous ones {continuous}, "
)
if planner in ("gradient", "cem"):
raise NotImplementedError(
lead + 'and it searches one kind of space: plan it with the "mixed" planner, '
"which enumerates the discrete nodes' policies and descends the continuous "
"controls of each, or score a mixed plan with System.score_policies"
)
raise NotImplementedError(
lead + 'and it does not search their product; the "mixed" planner does. Or score a '
"mixed plan with System.score_policies, or plan each part with a System of its own"
)
[docs]
class Planner(Protocol):
"""Policy inference over a :class:`PlannerContext`.
Returns ``(q_pi, tree, policies)``: the policy posterior, the term tree
(per-policy leaves aligned with ``q_pi``), and the planner's own policy set,
int32 ``(num_policies, policy_len, K)`` (one column per control node) or, over continuous
actions, float ``(num_policies, policy_len, action_dim)``. Callers sample
from these policies. ``metrics=False`` returns ``None`` for the tree and must
leave ``q_pi`` unchanged up to float reassociation. A planner that builds no
tree returns ``{}`` under ``metrics=True``.
A planner that takes a warm start carries the mark ``takes_init = True`` and accepts the
keyword ``init``, the continuous plan ``(policy_len, action_dim)`` its search starts from
(the gradient and mixed planners; :func:`planner_takes_init`).
"""
def __call__(
self, ctx: PlannerContext, use_bound: UseBound = "midpoint", metrics: bool = True
) -> tuple[Categorical, TermTree | None, Array]: ...
_PLANNERS: dict[str, Planner] = {}
[docs]
def register_planner(
name: str, *, needs_key: bool = False, branching: bool = False, legal_depth: bool = False
) -> Callable[[Planner], Planner]:
"""Decorator registering a planner under ``name`` for resolution by Systems.
``needs_key=True`` marks a stochastic planner, which reads
:attr:`PlannerContext.key`. ``branching=True`` marks a closed-loop planner that scores each
step on beliefs updated by the outcomes of earlier steps; it may be declared with a System's
``branch_on`` modalities, and when they are declared its context's step and terminal terms
score a state target by its cross-entropy rather than its KL (design:
per-variable-infogain.md V11 decisions 6 and 8). The marks are set on the function object,
so they travel with a planner passed as a callable: ``System.infer_policies`` / ``act`` then
require a ``plan_key`` for a stochastic planner and build the branching step terms for a
branching one. ``legal_depth=True`` marks a planner that reads
:attr:`PlannerContext.legal_steps`, masking the illegal actions at every depth of its plan;
a ``legal=`` mask given per step is then handed to it, and the System applies only the
first step's row to the policies the planner returns.
"""
stochastic, branches, per_depth = needs_key, branching, legal_depth
def register(fn: Planner) -> Planner:
fn.needs_key = stochastic # type: ignore[attr-defined]
fn.branching = branches # type: ignore[attr-defined]
fn.legal_depth = per_depth # type: ignore[attr-defined]
_PLANNERS[name] = fn
return fn
return register
[docs]
def planner_needs_key(planner: Planner) -> bool:
"""Whether ``planner`` declared itself stochastic (see :func:`register_planner`)."""
return bool(getattr(planner, "needs_key", False))
[docs]
def planner_branches(planner: Planner | str) -> bool:
"""Whether ``planner`` (a planner, or a registered name) declared itself branching (see
:func:`register_planner`); an unregistered name is not."""
if isinstance(planner, str):
planner = _PLANNERS.get(planner)
return bool(getattr(planner, "branching", False))
[docs]
def planner_takes_init(planner: Planner) -> bool:
"""Whether ``planner`` takes a warm start: the mark ``takes_init`` and the keyword ``init``
(see :class:`Planner`)."""
return bool(getattr(planner, "takes_init", False))
[docs]
def planner_legal_depth(planner: Planner) -> bool:
"""Whether ``planner`` declared that it masks illegal actions at every depth (see
:func:`register_planner`)."""
return bool(getattr(planner, "legal_depth", False))
[docs]
def get_planner(name: str) -> Planner:
"""The planner registered under ``name`` (:func:`register_planner`). An unknown name raises
:class:`KeyError`, listing the registered planners."""
if name not in _PLANNERS:
raise KeyError(
f"unknown planner {name!r}; registered planners: {sorted(_PLANNERS)}. "
"Use register_planner(name) to add one."
)
return _PLANNERS[name]