tscp 0.1.0.dev0__py3-none-any.whl

tscp/features/combine.py

@@ -0,0 +1,69 @@
+"""Several feature maps side by side."""
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.features.base import FeatureMap
+from tscp.registry import register
+
+
+def _element(values: Tensor) -> int:
+    """Number of element dimensions of ``[T, *element, ...]`` features or masks."""
+    return values.ndim - 2
+
+
+def _spread(values: Tensor, ndim: int, target: tuple[int, ...]) -> Tensor:
+    """Repeat ``[T, *element, ...]`` across missing leading element dimensions.
+
+    An element of ``()`` or ``(N,)`` lacks the leading dimensions of ``(H, N)``, so new
+    dimensions go right after the row dimension, not at the end.
+    """
+    missing = len(target) - ndim
+    for _ in range(missing):
+        values = values.unsqueeze(1)
+    return values.expand(values.shape[0], *target, *values.shape[1 + len(target) :])
+
+
+@register("features", "concat")
+class Concat(FeatureMap):
+    """Several feature maps side by side, broadcast to a common element shape.
+
+    A map per row (element ``()``) or per series (``(N,)``) is repeated over the steps
+    and series of a map per step and series (``(H, N)``), and the features are
+    concatenated. An element is valid where every map's features are.
+
+    Args:
+        maps: The feature maps, at least one.
+    """
+
+    def __init__(self, maps: list[FeatureMap]):
+        super().__init__()
+        if not maps:
+            raise ValueError("Concat needs at least one feature map")
+        self.maps = torch.nn.ModuleList(maps)
+
+    def _target(self, parts: list[Tensor]) -> tuple[int, ...]:
+        widest = max(parts, key=_element)
+        return tuple(widest.shape[1:-1])
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        parts = [feature_map(rows) for feature_map in self.maps]
+        target = self._target(parts)
+        spread = [_spread(part, _element(part), target) for part in parts]
+        return torch.cat(spread, dim=-1)
+
+    def valid(self, rows: ResidualArchive) -> Tensor | None:
+        parts = [feature_map(rows) for feature_map in self.maps]
+        target = self._target(parts)
+        masks = [feature_map.valid(rows) for feature_map in self.maps]
+        valid = None
+        for part, mask in zip(parts, masks, strict=True):
+            if mask is None:
+                continue
+            mask = _spread(mask.unsqueeze(-1), _element(part), target)[..., 0]
+            valid = mask if valid is None else valid & mask
+        return valid
+
+
+__all__ = ["Concat"]

tscp/features/context.py

@@ -0,0 +1,42 @@
+"""Columns of the archive's context."""
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.features.base import FeatureMap
+from tscp.registry import register
+
+
+@register("features", "context")
+class ContextColumns(FeatureMap):
+    """Columns of the archive's context: ``[T, F]``, or ``[T, N, F]`` for context per series.
+
+    Context holds covariates known at each origin, so a row may always use its own.
+
+    Args:
+        names: Names of the columns, from the archive's ``context_names``; None for all.
+    """
+
+    def __init__(self, names: list[str] | None = None):
+        super().__init__()
+        if names is not None and not names:
+            raise ValueError("names must name at least one column, or be None for all")
+        self.names = None if names is None else list(names)
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        if rows.context is None:
+            raise ValueError("this archive has no context")
+        context = rows.context
+        if not context.is_floating_point():
+            context = context.to(torch.get_default_dtype())
+        if self.names is None:
+            return context
+        unknown = sorted(set(self.names) - set(rows.context_names))
+        if unknown:
+            raise ValueError(f"the context has no columns {unknown}; it has {rows.context_names}")
+        index = torch.tensor([rows.context_names.index(name) for name in self.names])
+        return context[..., index.to(context.device)]
+
+
+__all__ = ["ContextColumns"]

tscp/features/history.py

@@ -0,0 +1,58 @@
+"""The residuals known before each origin."""
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.features.base import FeatureMap, timeline_of
+from tscp.registry import register
+
+
+@register("features", "history")
+class ResidualHistory(FeatureMap):
+    """The last ``lags`` known residuals of each step and series: ``[T, H, N, lags]``.
+
+    For a row with origin ``t``, lag 1 of step ``h`` is the most recent residual of step
+    ``h`` whose target time has passed by ``t``, lag 2 the one before, and so on. The
+    timeline's rows are in time order, so these are the last rows among the first
+    ``known_counts(t)[h]``. A lag that is not known yet, or whose target was not observed,
+    is 0 and makes the element invalid.
+
+    Args:
+        lags: Number of past residuals per step, positive.
+        absolute: Give absolute residuals.
+    """
+
+    def __init__(self, lags: int = 1, absolute: bool = False):
+        super().__init__()
+        if lags < 1:
+            raise ValueError("lags must be positive")
+        self.lags = int(lags)
+        self.absolute = bool(absolute)
+
+    def _history(self, rows: ResidualArchive) -> tuple[Tensor, Tensor]:
+        """Values and known mask, both ``[T, H, N, lags]``."""
+        timeline = timeline_of(rows)
+        device = timeline.device
+        counts = timeline.known_counts(rows.origins)  # [T, H]
+        index = counts[..., None] - torch.arange(1, self.lags + 1, device=device)  # [T, H, L]
+        safe = index.clamp(min=0)
+        steps = torch.arange(timeline.horizon, device=device)[None, :, None]
+        values = timeline.residuals.transpose(0, 1)[steps, safe]  # [T, H, L, N]
+        known = (index >= 0)[..., None].expand_as(values)
+        if timeline.observed is not None:
+            known = known & timeline.observed.transpose(0, 1)[steps, safe]
+        values = torch.where(known, values, torch.zeros((), dtype=values.dtype, device=device))
+        if self.absolute:
+            values = values.abs()
+        return values.permute(0, 1, 3, 2), known.permute(0, 1, 3, 2)
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        return self._history(rows)[0]
+
+    def valid(self, rows: ResidualArchive) -> Tensor | None:
+        known = self._history(rows)[1].all(dim=-1)
+        return None if bool(known.all()) else known
+
+
+__all__ = ["ResidualHistory"]

tscp/features/phase.py

@@ -0,0 +1,41 @@
+"""Where each origin falls in a cycle of base steps."""
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive
+from tscp.features.base import ENCODINGS, FeatureMap, encode_cycles
+from tscp.registry import register
+
+
+@register("features", "phase")
+class Phase(FeatureMap):
+    """The position of each origin in a cycle of ``period`` base steps: ``[T, F]``.
+
+    With hourly origins that start at midnight, ``Phase(24)`` is the hour of day; with
+    daily origins that start on a Monday, ``Phase(7)`` is the weekday. It needs no
+    timestamps. The ``"integer"`` encoding gives ``(origin + offset) mod period``, one
+    feature; ``"cyclic"`` gives its sine and cosine, two features.
+
+    Args:
+        period: Length of the cycle in base time steps, at least 2.
+        offset: Added to the origins before taking the remainder.
+        encoding: ``"integer"`` or ``"cyclic"``.
+    """
+
+    def __init__(self, period: int, offset: int = 0, encoding: str = "integer"):
+        super().__init__()
+        if period < 2:
+            raise ValueError("period must be at least 2")
+        if encoding not in ENCODINGS:
+            raise ValueError(f"encoding must be one of {ENCODINGS}, not {encoding!r}")
+        self.period = int(period)
+        self.offset = int(offset)
+        self.encoding = encoding
+
+    def forward(self, rows: ResidualArchive) -> Tensor:
+        phase = torch.remainder(rows.origins + self.offset, self.period)
+        return encode_cycles(phase[:, None], torch.tensor([self.period]), self.encoding)
+
+
+__all__ = ["Phase"]

tscp/imports.py

@@ -0,0 +1,32 @@
+"""Guards for optional dependencies.
+
+Core tscp needs only torch and numpy. A component that needs another package imports it
+through :func:`require`, so the error names the extra that provides it.
+"""
+
+import importlib
+import importlib.util
+from types import ModuleType
+
+
+def has_module(name: str) -> bool:
+    """Return whether ``name`` can be imported, without importing it."""
+    return importlib.util.find_spec(name) is not None
+
+
+def require(name: str, extra: str | None = None) -> ModuleType:
+    """Import an optional dependency, or raise an ImportError that says how to install it.
+
+    Args:
+        name: Module to import, such as ``"scipy"``.
+        extra: The tscp extra that provides it, if there is one.
+    """
+    try:
+        return importlib.import_module(name)
+    except ImportError as error:
+        hint = f"pip install 'tscp[{extra}]'" if extra else f"pip install {name}"
+        message = f"{name} is needed for this feature; install it with `{hint}`."
+        raise ImportError(message) from error
+
+
+__all__ = ["has_module", "require"]

tscp/methods/__init__.py

@@ -0,0 +1,48 @@
+"""Published methods as presets: one choice per axis, run by :class:`ConformalPredictor`.
+
+Presets are registered in :mod:`tscp.registry` under the kind ``"method"``;
+:data:`method_map` is that table, and :func:`get_method` builds a preset by name, as
+poolers are built in tgp. :func:`compose` builds a method from a spec of short names.
+"""
+
+from tscp import registry
+
+from .aci import ACI
+from .base import AXES, ConformalPredictor
+from .compose import compose
+from .io import load_method, save_method
+from .nexcp import NexCP
+from .split import SplitCP
+
+method_map: dict[str, type[ConformalPredictor]] = registry.entries("method")
+"""Registered presets by short name: the live table of :mod:`tscp.registry`."""
+
+
+def get_method(name: str, *, ignore_unknown: bool = False, **kwargs) -> ConformalPredictor:
+    """Build a registered preset by name.
+
+    Args:
+        name: A registered method name, in any case; installed plugins count.
+        ignore_unknown: Drop keyword arguments the preset does not take, which helps when
+            one config sweeps several presets. By default they raise.
+        **kwargs: Arguments of the preset.
+
+    Raises:
+        ValueError: If ``name`` is not registered.
+        TypeError: If an argument is unknown and ``ignore_unknown`` is False.
+    """
+    return registry.build("method", name, ignore_unknown=ignore_unknown, **kwargs)
+
+
+__all__ = [
+    "ACI",
+    "AXES",
+    "ConformalPredictor",
+    "NexCP",
+    "SplitCP",
+    "compose",
+    "get_method",
+    "load_method",
+    "method_map",
+    "save_method",
+]

tscp/methods/aci.py

@@ -0,0 +1,44 @@
+"""Adaptive conformal inference on top of conformal thresholds."""
+
+from tscp.methods.base import ConformalPredictor
+from tscp.online import ACIUpdate
+from tscp.registry import register
+from tscp.scores import AbsoluteScore, Score
+from tscp.sources import ExpandingSource, Source
+
+
+@register("method", "aci")
+class ACI(ConformalPredictor):
+    """Adaptive conformal inference (Gibbs & Candès, NeurIPS 2021).
+
+    The threshold at each test origin is the conformal quantile at the current level
+    ``alpha_t``, which :class:`~tscp.online.ACIUpdate` moves after every released
+    outcome. The long-run miss rate converges to ``alpha`` on any sequence.
+
+    Deviation from the paper: the paper recalibrates on a recent window after refitting
+    its model. tscp never refits the forecaster; the pool here is the calibration split
+    plus every test residual already known (the expanding source).
+
+    Args:
+        gamma: Step size of the level update.
+        score: Defaults to :class:`~tscp.scores.AbsoluteScore`.
+        source: Defaults to :class:`~tscp.sources.ExpandingSource`.
+        alpha: Target miscoverage level.
+    """
+
+    def __init__(
+        self,
+        gamma: float = 0.005,
+        score: Score | None = None,
+        source: Source | None = None,
+        alpha: float = 0.1,
+    ):
+        super().__init__(
+            score=score if score is not None else AbsoluteScore(),
+            source=source if source is not None else ExpandingSource(),
+            update=ACIUpdate(gamma),
+            alpha=alpha,
+        )
+
+
+__all__ = ["ACI"]

tscp/methods/base.py

@@ -0,0 +1,228 @@
+"""The composer that runs one component per axis as a conformal method."""
+
+import math
+from collections.abc import Iterator
+from typing import Self
+
+import torch
+from torch import Tensor
+
+from tscp.data import ResidualArchive, availability_mask
+from tscp.methods.engine import OnlineEngine, replay
+from tscp.online import OnlineUpdate
+from tscp.quantile import Pool, QuantileModel, ScoreDistribution, WeightedQuantile
+from tscp.regions import Region
+from tscp.scores import Score
+from tscp.sources import HoldoutSource, Source
+from tscp.utils import Component
+from tscp.weights import Weights
+
+AXES = ("score", "source", "weights", "quantile", "update")
+"""Attribute names of the axis components."""
+
+_AXIS_TYPES = {
+    "score": Score,
+    "source": Source,
+    "weights": Weights,
+    "quantile": QuantileModel,
+    "update": OnlineUpdate,
+}
+_MAX_ELEMENTS = 2**23
+
+
+class ConformalPredictor(Component):
+    """A conformal method: one component per axis, run through a fixed lifecycle.
+
+    1. :meth:`fit` fits every trainable component on ``archive.split("fit")``, with the
+       ``validation`` split if there is one, and on nothing else.
+    2. :meth:`calibrate` scores the source's rows, the calibration split.
+    3. :meth:`predict` makes one region per test origin, in residual coordinates.
+
+    Evaluation is a separate step (:func:`tscp.metrics.evaluate`).
+
+    For each chunk of test origins, :meth:`predict` asks the quantile model for the
+    conformal distribution of the score given the pool and its weights. Without an online
+    update it reads every threshold from those distributions at the score's levels. With
+    one, it answers the test origins in time order and hands the update each outcome once
+    its target time has passed (:mod:`tscp.methods.engine`). An expanding source adds each
+    test residual to the pool by the same rule. For a per-step score, step ``h`` of an
+    origin becomes known ``h`` base steps after it; for a score over the whole horizon,
+    after the last step.
+
+    Args:
+        score: Axis 2, how an error becomes a number.
+        source: Axis 1, which past errors calibrate; the calibration split by default.
+        weights: Axis 3; None weighs every available pool residual equally.
+        quantile: Axis 4; :class:`~tscp.quantile.WeightedQuantile` by default.
+        update: Axis 5; None for an offline method.
+        alpha: Target miscoverage level, in (0, 1).
+        chunk_size: Most query origins whose weights are held in memory at once.
+    """
+
+    def __init__(
+        self,
+        score: Score,
+        source: Source | None = None,
+        weights: Weights | None = None,
+        quantile: QuantileModel | None = None,
+        update: OnlineUpdate | None = None,
+        alpha: float = 0.1,
+        chunk_size: int = 256,
+    ):
+        super().__init__()
+        if not 0 < alpha < 1:
+            raise ValueError("alpha must lie in (0, 1)")
+        if chunk_size < 1:
+            raise ValueError("chunk_size must be positive")
+        self.score = score
+        self.source = source if source is not None else HoldoutSource()
+        self.weights = weights
+        self.quantile = quantile if quantile is not None else WeightedQuantile()
+        self.update = update
+        for axis, expected in _AXIS_TYPES.items():
+            component = getattr(self, axis)
+            if component is not None and not isinstance(component, expected):
+                raise TypeError(f"{axis} must be a {expected.__name__}, not {type(component)}")
+        self.alpha = float(alpha)
+        self.chunk_size = int(chunk_size)
+        self.fit_fingerprint: str | None = None
+        # Calibration state: moves with .to(device), stays out of state_dict().
+        self.register_buffer("pool_scores", None, persistent=False)
+        self.register_buffer("pool_origins", None, persistent=False)
+        self.register_buffer("pool_valid", None, persistent=False)
+
+    def components(self) -> dict[str, Component]:
+        """Return the components that are set, keyed by axis."""
+        return {axis: getattr(self, axis) for axis in AXES if getattr(self, axis) is not None}
+
+    @property
+    def is_trainable(self) -> bool:
+        return any(component.is_trainable for component in self.components().values())
+
+    # -- lifecycle -----------------------------------------------------------------------
+
+    def fit(self, archive: ResidualArchive) -> Self:
+        """Fit every trainable component on the ``fit`` split, and ``validation`` if any."""
+        trainable = [axis for axis, c in self.components().items() if c.is_trainable]
+        if not trainable:
+            return self
+        if archive.splits is None or "fit" not in archive.splits:
+            names = ", ".join(trainable)
+            raise ValueError(f"{names} must be fitted, and the archive has no 'fit' split")
+        train = archive.split("fit")
+        validation = archive.split("validation") if "validation" in archive.splits else None
+        for axis in trainable:
+            getattr(self, axis).fit(train, validation)
+        # Which data the fitted state came from, for saved methods (tscp.methods.io).
+        self.fit_fingerprint = archive.fingerprint()
+        return self
+
+    def calibrate(self, archive: ResidualArchive) -> Self:
+        """Score the calibration pool of ``archive``."""
+        pool = archive.select(self.source.rows(archive))
+        self.pool_scores = self.score(pool)
+        self.pool_origins = pool.origins
+        self.pool_valid = self.score.valid(pool)
+        return self
+
+    def predict(self, archive: ResidualArchive) -> Region:
+        """Return one region per origin of the ``test`` split, in residual coordinates."""
+        if self.pool_scores is None:
+            raise RuntimeError("calibrate() must run before predict()")
+        rows = self.source.rows(archive)
+        if not torch.equal(archive.origins[rows], self.pool_origins):
+            raise ValueError("predict() must get the archive that calibrate() got")
+        if archive.splits is None or "test" not in archive.splits:
+            raise ValueError("predict() needs an archive with a 'test' split")
+        test_rows = archive.splits["test"]
+        query = archive.select(test_rows)
+        query_scores = self.score(query)
+        query_valid = self.score.valid(query)
+        if self.source.expanding:
+            # Test residuals join the pool; the availability mask releases each one only
+            # after its target time.
+            pool = Pool(
+                torch.cat([self.pool_scores, query_scores]),
+                archive.select(torch.cat([rows, test_rows])),
+                _concat_valid(self.pool_valid, query_valid, self.pool_scores, query_scores),
+            )
+        else:
+            pool = Pool(self.pool_scores, archive.select(rows), self.pool_valid)
+        thresholds = self._thresholds(pool, query, query_scores, query_valid)
+        return self.score.region(thresholds, query)
+
+    # -- internals -----------------------------------------------------------------------
+
+    def _thresholds(
+        self,
+        pool: Pool,
+        query: ResidualArchive,
+        query_scores: Tensor,
+        query_valid: Tensor | None,
+    ) -> Tensor:
+        kept = pool.kept
+        levels = self.score.levels(self.alpha, kept).to(pool.scores.device)
+        step_kept = "step" not in self.score.reduce_dims
+        # Steps after which each group of kept elements becomes known.
+        offsets = query.steps if step_kept else query.steps[-1:]
+        out = torch.empty((len(query), *kept), dtype=pool.scores.dtype, device=pool.scores.device)
+        chunks = self._distributions(pool, query, offsets, step_kept)
+        if self.update is None:
+            for start, stop, distribution in chunks:
+                out[start:stop] = distribution.threshold(levels)
+            return out
+        engine = OnlineEngine(self.update, levels, step_kept, len(offsets))
+        return replay(engine, query.origins, offsets, chunks, query_scores, query_valid, out)
+
+    def _distributions(
+        self, pool: Pool, query: ResidualArchive, offsets: Tensor, step_kept: bool
+    ) -> Iterator[tuple[int, int, ScoreDistribution]]:
+        """Yield ``(start, stop, distribution)`` for consecutive chunks of the queries."""
+        uniform = self.weights is None and not self.source.expanding and pool.valid is None
+        chunk = self.chunk_size
+        if not uniform:
+            chunk = max(1, min(chunk, _MAX_ELEMENTS // (len(pool) * math.prod(pool.kept))))
+        for start in range(0, len(query), chunk):
+            stop = min(start + chunk, len(query))
+            rows = query.select(torch.arange(start, stop, device=query.device))
+            weights = None if uniform else self._weights(pool, rows, offsets, step_kept)
+            yield start, stop, self.quantile(pool, weights, rows)
+
+    def _weights(
+        self, pool: Pool, rows: ResidualArchive, offsets: Tensor, step_kept: bool
+    ) -> Tensor:
+        """Weights ``[c, P, ...]`` for the ``c`` query ``rows``, with every mask applied."""
+        kept_ndim = len(pool.kept)
+        device = pool.scores.device
+        weights = torch.ones(len(rows), len(pool), dtype=torch.float64, device=device)
+        if self.weights is not None:
+            weights = self.weights(pool.rows, rows).to(torch.float64)
+        weights = weights.reshape(*weights.shape, *([1] * (2 + kept_ndim - weights.ndim)))
+        if self.source.expanding:
+            mask = availability_mask(pool.rows.origins, rows.origins, offsets)
+            weights = weights * _group_mask(mask, step_kept, kept_ndim)
+        if pool.valid is not None:
+            weights = weights * pool.valid.unsqueeze(0)
+        return weights
+
+
+def _group_mask(mask: Tensor, step_kept: bool, kept_ndim: int) -> Tensor:
+    """Reshape a ``[Q, P, G]`` availability mask to broadcast over ``[Q, P, *kept]``."""
+    if step_kept:  # one group per step, and step is the first kept dimension
+        return mask.reshape(*mask.shape, *([1] * (kept_ndim - 1)))
+    return mask[..., 0].reshape(*mask.shape[:2], *([1] * kept_ndim))
+
+
+def _concat_valid(
+    pool_valid: Tensor | None, query_valid: Tensor | None, pool_scores: Tensor, query_scores: Tensor
+) -> Tensor | None:
+    if pool_valid is None and query_valid is None:
+        return None
+    if pool_valid is None:
+        pool_valid = torch.ones_like(pool_scores, dtype=torch.bool)
+    if query_valid is None:
+        query_valid = torch.ones_like(query_scores, dtype=torch.bool)
+    return torch.cat([pool_valid, query_valid])
+
+
+__all__ = ["AXES", "ConformalPredictor"]

tscp/methods/compose.py

@@ -0,0 +1,90 @@
+"""Methods built from specs of short names, such as specs read from YAML."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from tscp import registry
+from tscp.methods.base import AXES, ConformalPredictor
+from tscp.utils import Component, from_config
+
+_SETTINGS = ("alpha", "chunk_size")
+
+
+def compose(spec: Mapping[str, Any]) -> ConformalPredictor:
+    """Build a method from a spec.
+
+    A spec names either a registered preset with its arguments::
+
+        {"method": "nexcp", "decay": 0.99, "alpha": 0.1}
+
+    or one component per axis, run by :class:`~tscp.methods.ConformalPredictor`::
+
+        {
+            "score": "signed",
+            "source": "expanding",
+            "weights": {"name": "exponential", "decay": 0.99},
+            "update": {"name": "aci", "gamma": 0.005},
+            "alpha": 0.1,
+        }
+
+    A component can be given as its short name, as ``{"name": ..., **arguments}``, as a
+    full config ``{"class": ..., "args": ...}`` (what
+    :meth:`~tscp.utils.ConfigMixin.to_config` returns), or as a component. Inside
+    arguments, a component of another kind states its kind:
+    ``{"kind": "features", "name": "phase", "period": 24}``. Names come from
+    :mod:`tscp.registry`, so installed plugins can be named too.
+
+    Raises:
+        ValueError: If the spec has unknown keys, no score, or names nothing registered.
+    """
+    spec = dict(spec)
+    if "method" in spec:
+        name = spec.pop("method")
+        arguments = {
+            key: _component(key, value) if key in AXES else _resolve(value)
+            for key, value in spec.items()
+        }
+        return registry.build("method", name, **arguments)
+    unknown = sorted(set(spec) - set(AXES) - set(_SETTINGS))
+    if unknown:
+        raise ValueError(
+            f"unknown keys {unknown} in a spec; use 'method' for a preset, or the axes "
+            f"{AXES} and the settings {_SETTINGS}"
+        )
+    if "score" not in spec:
+        raise ValueError("a spec needs a 'score', or a 'method' that names a preset")
+    arguments = {
+        key: _component(key, value) if key in AXES else value for key, value in spec.items()
+    }
+    return ConformalPredictor(**arguments)
+
+
+def _component(kind: str, value: Any) -> Any:
+    """Build a component of ``kind`` from any of the forms a spec allows."""
+    if value is None or isinstance(value, Component):
+        return value
+    if isinstance(value, str):
+        return registry.build(kind, value)
+    if isinstance(value, Mapping):
+        if set(value) == {"class", "args"}:
+            return from_config(value)
+        if "name" in value:
+            arguments = {k: _resolve(v) for k, v in value.items() if k not in ("name", "kind")}
+            return registry.build(value.get("kind", kind), value["name"], **arguments)
+    raise ValueError(f"cannot build a {kind} from {value!r}")
+
+
+def _resolve(value: Any) -> Any:
+    """Build the components nested in an argument value; leave other values alone."""
+    if isinstance(value, Mapping):
+        if set(value) == {"class", "args"}:
+            return from_config(value)
+        if "kind" in value and "name" in value:
+            return _component(value["kind"], value)
+        return {key: _resolve(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_resolve(item) for item in value]
+    return value
+
+
+__all__ = ["compose"]