Core 基础能力
Typed registry、规范化 helper、确定性工具、图像组合与可复用安全 guardrail protocol。
基础 Core API 看起来很小，但它们定义了许多大型系统共同使用的约定：标识符规范化、确定性 registry、环境 flag、精确整除、list 归一化、图像物化与组合、随机种子和安全接口。
Typed registry 示例
from worldfoundry.core import TypedRegistry
metrics = TypedRegistry()
metrics.register(
"temporal-consistency",
object(),
aliases=("temporal", "tc"),
metadata={"direction": "higher-is-better"},
)
assert metrics.get("TC") is metrics.get("temporal-consistency")
assert metrics.keys() == ("temporal-consistency",)Key 和 alias 会经过 strip 与 case-fold 后查找，但 RegistryItem 会保留原始公开 key。注册冲突会显式报错，不会静默覆盖；枚举顺序是确定的，因此生成 manifest 和测试结果也稳定。
Guardrail 组合示例
from worldfoundry.core.safety import GuardrailRunner
class RejectEmptyPrompt:
def is_safe(self, value):
prompt = str(value).strip()
return (bool(prompt), "prompt is empty" if not prompt else "")
runner = GuardrailRunner(
safety_models=[RejectEmptyPrompt()],
generic_block_msg="Request rejected",
)
assert runner.run_safety_check("walk through a snowy forest")[0] is True
assert runner.run_safety_check("") == (False, "Request rejected")ContentSafetyGuardrail 和 PostprocessingGuardrail 是结构化 protocol：实现只需要提供文档声明的方法。GuardrailRunner 在第一个不安全 classifier 处停止，并在需要时按顺序应用 postprocessor。classifier list 为空时，它会告警并返回安全；生产策略必须明确决定这种 fail-open 行为是否可接受。
Safety package 会从模型 runtime 环境导入 NumPy 和基于 Loguru 的 rank-aware logging。Registry 示例本身只使用 import-light 的 Core 顶层 facade。
工具边界
env_is_true 只识别有限的 truthy 词表，并不是通用 parser。divide 会断言精确整除，适合形状或 group invariant。as_list 在 API 边界把标量或 sequence 规范成 list。set_random_seed 会协调常见随机后端，但仅靠它不能保证 CUDA kernel 完全确定。
图像 helper 会在各自文档声明的范围内接受路径、PIL image、array 或 tensor。compose_horizontal_views 和 split_horizontal_views 会遵守指定 view 顺序；应让这个顺序与 artifact 一起保存，不要让后续 reader 猜测。
完整参考
以下为该类别的生成签名。可用本页符号索引跳转；源码链接指向各惰性导出背后的具体实现。
23 个公开符号
def clear_inference_runtime_cache(cache: MutableMapping[Any, Any]) -> Noneworldfoundry.core.clear_inference_runtime_cachefrom worldfoundry.core import clear_inference_runtime_cache简介
clear_inference_runtime_cache — Drop cached runtimes and release unreferenced accelerator allocations. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：None。
源码 docstring
Drop cached runtimes and release unreferenced accelerator allocations.
The torch import is intentionally lazy so model discovery remains cheap in processes that never execute a PyTorch policy. `empty_cache` only returns already-unreferenced blocks to the CUDA allocator; clearing the strong references and collecting cycles must happen first.
参数
cacheMutableMapping[Any, Any]
返回值: None
def compose_horizontal_views(images,target_size: tuple[int, int] | None = None) -> Image.Imageworldfoundry.core.compose_horizontal_viewsfrom worldfoundry.core import compose_horizontal_views简介
compose_horizontal_views — Resize optional per-view images and concatenate them horizontally. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：Image.Image。
参数
imagestarget_sizetuple[int, int] | None- 默认值:
None
返回值: Image.Image
class ContentSafetyGuardrail(Protocol)worldfoundry.core.safety.ContentSafetyGuardrailfrom worldfoundry.core.safety import ContentSafetyGuardrail简介
ContentSafetyGuardrail — Interface implemented by prompt and media safety classifiers. 属于 Core 基础能力（registry、通用工具、安全契约）。
方法
简介
is_safe — Return whether `input` is safe and an optional explanation.
参数
inputAny
返回值: tuple[bool, str]
divide
funcdef divide(numerator: int, denominator: int) -> intworldfoundry.core.dividefrom worldfoundry.core import divide简介
divide — Return exact integer division and reject a non-divisible numerator. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：int。
参数
numeratorintdenominatorint
异常
AssertionError- `
numeratoris not divisible bydenominator`.
返回值: int
class DuplicateRegistryKeyError()worldfoundry.core.DuplicateRegistryKeyErrorfrom worldfoundry.core import DuplicateRegistryKeyError简介
DuplicateRegistryKeyError — Raised when a key or alias maps to multiple different entries. 属于 Core 基础能力（registry、通用工具、安全契约）。
env_is_true
funcdef env_is_true(env_name: str) -> boolworldfoundry.core.env_is_truefrom worldfoundry.core import env_is_true简介
env_is_true — Return whether an environment variable uses a recognized truthy spelling. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：bool。
参数
env_namestr
返回值: bool
class GuardrailRunner(safety_models: Sequence[ContentSafetyGuardrail] | None = None,generic_block_msg: str = '',generic_safe_msg: str = '',postprocessors: Sequence[PostprocessingGuardrail] | None = None)worldfoundry.core.safety.GuardrailRunnerfrom worldfoundry.core.safety import GuardrailRunner简介
GuardrailRunner — Run reusable safety classifiers and postprocessors in sequence. 属于 Core 基础能力（registry、通用工具、安全契约）。
参数
safety_modelsSequence[ContentSafetyGuardrail] | None- Ordered classifiers. Evaluation stops on the first unsafe result.默认值:
None generic_block_msgstr- Optional public message replacing classifier details when a request is blocked.默认值:
'' generic_safe_msgstr- Message returned after all classifiers pass.默认值:
'' postprocessorsSequence[PostprocessingGuardrail] | None- Ordered frame transforms applied by `
postprocess`.默认值:None
方法
简介
run_safety_check — Run classifiers in order and return the first block or final safe result.
参数
inputAny
返回值: tuple[bool, str]
简介
postprocess — Apply every configured safety postprocessor to a frame array.
参数
framesnp.ndarray
返回值: np.ndarray
load_pil_image
funcdef load_pil_image(image_input, , first_sequence_item: bool = True) -> Image.Imageworldfoundry.core.load_pil_imagefrom worldfoundry.core import load_pil_image简介
load_pil_image — Normalize a path, PIL image, numpy array, torch tensor, or sequence to RGB PIL. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：Image.Image。
参数
image_inputfirst_sequence_itembool- 默认值:
True
返回值: Image.Image
def materialize_image_input(image_input,output_dir: str | os.PathLike[str],filename: str = 'input.png') -> strworldfoundry.core.materialize_image_inputfrom worldfoundry.core import materialize_image_input简介
materialize_image_input — Normalize an image-like input and save it at a stable local path. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：str。
参数
image_inputoutput_dirstr | os.PathLike[str]filenamestr- 默认值:
'input.png'
返回值: str
def normalize_action_values(values: Any,statistics: Mapping[str, Any],mode: str = 'min_max',clip: float | None = None) -> np.ndarrayworldfoundry.core.normalize_action_valuesfrom worldfoundry.core import normalize_action_values简介
normalize_action_values — Normalize action values using checkpoint statistics along the last axis. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：np.ndarray。
参数
valuesAnystatisticsMapping[str, Any]modestr- 默认值:
'min_max' clipfloat | None- 默认值:
None
返回值: np.ndarray
def normalize_registry_key(value: str, , field_name: str = 'registry key') -> strworldfoundry.core.normalize_registry_keyfrom worldfoundry.core import normalize_registry_key简介
normalize_registry_key — Normalize a user-facing registry key for case-insensitive lookup. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：str。
参数
valuestrfield_namestr- 默认值:
'registry key'
返回值: str
class PostprocessingGuardrail(Protocol)worldfoundry.core.safety.PostprocessingGuardrailfrom worldfoundry.core.safety import PostprocessingGuardrail简介
PostprocessingGuardrail — Interface implemented by safety postprocessors such as face blurring. 属于 Core 基础能力（registry、通用工具、安全契约）。
方法
简介
postprocess — Return safety-processed frames.
参数
framesnp.ndarray
返回值: np.ndarray
class RegistryError()worldfoundry.core.RegistryErrorfrom worldfoundry.core import RegistryError简介
RegistryError — Base class for registry definition errors. 属于 Core 基础能力（registry、通用工具、安全契约）。
RegistryItem
clsclass RegistryItem(key: str,value: ItemT,aliases: tuple[str, ...] = (),metadata: Mapping[str, object] = <dict factory>)worldfoundry.core.RegistryItemfrom worldfoundry.core import RegistryItem简介
RegistryItem — One registered item plus its public aliases. 属于 Core 基础能力（registry、通用工具、安全契约）。
属性
keystrvalueItemTaliasestuple[str, ...]- 默认值:
() metadataMapping[str, object]- 默认值:
<dict factory>
def select_modality_statistics(dataset_statistics: Mapping[str, Any],modality: str = 'action',key: str | None = None) -> tuple[str | None, Mapping[str, Any]]worldfoundry.core.select_modality_statisticsfrom worldfoundry.core import select_modality_statistics简介
select_modality_statistics — Select one modality's statistics from a checkpoint statistics mapping. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：tuple[str | None, Mapping[str, Any]]。
源码 docstring
Select one modality's statistics from a checkpoint statistics mapping.
Both common layouts are accepted: a direct `{"min": ..., "max": ...} mapping and a dataset-keyed {"robot": {"action": {...}}}` mapping. Dataset-key selection is strict when more than one key is available.
参数
dataset_statisticsMapping[str, Any]modalitystr- 默认值:
'action' keystr | None- 默认值:
None
返回值: tuple[str | None, Mapping[str, Any]]
set_random_seed
funcdef set_random_seed(seed: int, by_rank: bool = False) -> intworldfoundry.core.set_random_seedfrom worldfoundry.core import set_random_seed简介
set_random_seed — Set Python, NumPy, and PyTorch seeds with optional distributed-rank offset. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：int。
参数
seedintby_rankbool- 默认值:
False
返回值: int
def split_horizontal_views(image,num_views: int,target_size: tuple[int, int] | None = None) -> list[Image.Image]worldfoundry.core.split_horizontal_viewsfrom worldfoundry.core import split_horizontal_views简介
split_horizontal_views — Split a horizontally concatenated image into equally sized RGB views. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：list[Image.Image]。
参数
imagenum_viewsinttarget_sizetuple[int, int] | None- 默认值:
None
返回值: list[Image.Image]
def stack_or_pad_tensors(values: Sequence[Tensor],padding_value: float | int | bool | None = None) -> Tensorworldfoundry.core.stack_or_pad_tensorsfrom worldfoundry.core import stack_or_pad_tensors简介
stack_or_pad_tensors — Stack equal tensors or right-pad variable-length 1-D tensors. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：Tensor。
源码 docstring
Stack equal tensors or right-pad variable-length 1-D tensors.
This is the common collation shape used by multimodal policies whose dense image/state inputs are fixed while token and mask lengths may vary. More complex shape mismatches are rejected instead of being padded silently.
参数
valuesSequence[Tensor]padding_valuefloat | int | bool | None- 默认值:
None
返回值: Tensor
class TypedRegistry(items: Iterable[RegistryItem[ItemT]] = ())worldfoundry.core.TypedRegistryfrom worldfoundry.core import TypedRegistry简介
TypedRegistry — Deterministic keyed registry with alias support. 属于 Core 基础能力（registry、通用工具、安全契约）。
源码 docstring
Deterministic keyed registry with alias support.
Registration methods (mutate state): - `register(key, value, ...)` — add one item and its aliases.
Lookup methods (read state): - `get(key) / get_item(key) — resolve a key or alias. - keys / values / items / aliases` — enumerate entries.
参数
itemsIterable[RegistryItem[ItemT]]- 默认值:
()
异常
DuplicateRegistryKeyError- On conflicting keys or aliases.
UnknownRegistryKeyError- When a lookup cannot be resolved.
方法
register(key: str,value: ItemT,aliases: Iterable[str] = (),metadata: Mapping[str, object] | None = None) -> RegistryItem[ItemT]源码简介
register — Register an item and return the normalized registry record.
参数
keystrvalueItemTaliasesIterable[str]- 默认值:
() metadataMapping[str, object] | None- 默认值:
None
返回值: RegistryItem[ItemT]
简介
get — Resolve a key or alias to the registered value.
参数
keystr
返回值: ItemT
简介
keys — Return canonical keys in deterministic order.
返回值: tuple[str, ...]
简介
aliases — Return normalized alias to normalized canonical key mapping.
返回值: Mapping[str, str]
简介
items — Return registry items sorted by their public key.
返回值: tuple[RegistryItem[ItemT], ...]
简介
values — Return registered values sorted by public key.
返回值: tuple[ItemT, ...]
class UnknownRegistryKeyError()worldfoundry.core.UnknownRegistryKeyErrorfrom worldfoundry.core import UnknownRegistryKeyError简介
UnknownRegistryKeyError — Raised when a registry lookup cannot be resolved. 属于 Core 基础能力（registry、通用工具、安全契约）。
def unnormalize_action_values(normalized_values: Any,statistics: Mapping[str, Any],mode: str = 'min_max') -> np.ndarrayworldfoundry.core.unnormalize_action_valuesfrom worldfoundry.core import unnormalize_action_values简介
unnormalize_action_values — Convert normalized policy outputs back to environment-space actions. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：np.ndarray。
参数
normalized_valuesAnystatisticsMapping[str, Any]modestr- 默认值:
'min_max'
返回值: np.ndarray