Skip to content

atomref.policy

This module contains the generic resolver that sits below the radii-specific and X–H-specific convenience APIs.

Use it when you want to work directly with the shared value-selection engine:

  • ValuePolicy — generic element-domain policy configuration,
  • lookup_value(...) — resolve one value together with provenance,
  • get_value(...) — resolve only the numeric value,
  • LookupResult — the structured result object returned by the resolver.

A few practical notes:

  • The current runtime supports element-domain scalar policies.
  • ValuePolicy normalizes element-symbol overrides eagerly.
  • Transfer sources may be packaged datasets, custom sets, generic policies, or wrapper policies that expose as_value_policy().
  • LookupResult.is_placeholder refers to the returned numeric value itself, not to whether any transfer happened.
  • LookupResult.transfer_depth counts how many transfer steps were involved in the returned numeric value.
  • Nested lookup is cycle-checked across both generic ValuePolicy objects and wrapper policies such as RadiiPolicy and XHPolicy.

atomref.policy

Generic value-policy resolution for element-indexed scalar datasets.

LookupResult dataclass

Result of resolving one value through a policy.

value carries the final scalar value when one could be produced, while source and the remaining metadata explain how that value was obtained. transfer_depth counts how many transfer steps were involved in producing the returned value. Direct base and override values therefore have depth 0.

__float__()

Coerce the resolved value to float or raise if it is missing.

ValuePolicy dataclass

Bases: Generic[K]

Ordered rule set for resolving element-domain scalar values.

The current runtime resolves only element-domain policies even though the metadata layer already records a more general domain concept. During construction, element-domain override keys are normalized to canonical element symbols and validated as finite floats.

__post_init__()

Validate and normalize policy configuration eagerly.

get_value(symbol, *, policy)

Return only the resolved scalar value for an element-domain policy.

lookup_value(symbol, *, policy)

Public entry point for generic element-domain scalar lookup.

This is the same resolver used internally by the radii convenience layer. In the current implementation the runtime supports only element-domain policies.