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 猜测。
完整参考
以下为该类别的生成签名。可用本页符号索引跳转；源码链接指向各惰性导出背后的具体实现。
26 个公开符号
def batched_image_features(images: torch.Tensor,encoder: Callable[[torch.Tensor], torch.Tensor],device: torch.device | str | int,batch_size: int | None = None,default_batch_size: int = 32,scope: str = 'image_features',normalize: bool = False,output_device: torch.device | str | int | None = 'cpu',batch_size_buckets: Sequence[int] | None = None) -> torch.Tensorbatched_image_features — Encode images with OOM backoff and shape-stable tail padding. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：torch.Tensor。
参数
imagestorch.TensorencoderCallable[[torch.Tensor], torch.Tensor]devicetorch.device | str | intbatch_sizeint | None默认值 Nonedefault_batch_sizeint默认值 32scopestr默认值 'image_features'normalizebool默认值 Falseoutput_devicetorch.device | str | int | None默认值 'cpu'batch_size_bucketsSequence[int] | None默认值 None返回值
def compose_horizontal_views(images,target_size: tuple[int, int] | None = None) -> Image.Imagecompose_horizontal_views — Resize optional per-view images and concatenate them horizontally. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：Image.Image。
参数
imagestarget_sizetuple[int, int] | None默认值 None返回值
class ContentSafetyGuardrail(Protocol)ContentSafetyGuardrail — Interface implemented by prompt and media safety classifiers. 属于 Core 基础能力（registry、通用工具、安全契约）。
方法
is_safe — Return whether `input` is safe and an optional explanation.
参数
inputAny返回值
class DuplicateRegistryKeyError()DuplicateRegistryKeyError — Raised when a key or alias maps to multiple different entries. 属于 Core 基础能力（registry、通用工具、安全契约）。
def env_is_true(env_name: str) -> boolenv_is_true — Return whether an environment variable uses a recognized truthy spelling. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：bool。
参数
env_namestr返回值
class GuardrailRunner(safety_models: Sequence[ContentSafetyGuardrail] | None = None,generic_block_msg: str = '',generic_safe_msg: str = '',postprocessors: Sequence[PostprocessingGuardrail] | None = None)GuardrailRunner — Run reusable safety classifiers and postprocessors in sequence. 属于 Core 基础能力（registry、通用工具、安全契约）。
参数
generic_block_msgstr默认值 ''generic_safe_msgstr默认值 ''postprocess`.方法
简介
run_safety_check — Run classifiers in order and return the first block or final safe result.
源码 docstring
Run classifiers in order and return the first block or final safe result.
Note the deliberate fail-open default: with no configured safety models the input is reported safe (with a warning). Deployments that require enforcement must configure at least one classifier.
参数
inputAny返回值
postprocess — Apply every configured safety postprocessor to a frame array.
参数
framesnp.ndarray返回值
def load_pil_image(image_input,first_sequence_item: bool = True) -> Image.Imageload_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返回值
def materialize_image_input(image_input,output_dir: str | os.PathLike[str],filename: str = 'input.png') -> strmaterialize_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'返回值
def mean_pairwise_cosine_distance(features: Sequence[torch.Tensor]) -> floatmean_pairwise_cosine_distance — Return the mean cosine distance across all unordered feature pairs. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：float。
参数
featuresSequence[torch.Tensor]返回值
def normalize_action_values(values: Any,statistics: Mapping[str, Any],mode: str = 'min_max',clip: float | None = None) -> np.ndarraynormalize_action_values — Normalize action values using checkpoint statistics along the last axis. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：np.ndarray。
参数
valuesAnystatisticsMapping[str, Any]select_modality_statistics.modestr默认值 'min_max'min_max (default), q99 / quantile / bounds, mean_std / standard / zscore, or identity`.clipfloat | None默认值 None[-clip, clip]` after normalization.返回值
float` array with the same shape as *values*.def normalize_registry_key(value: str,field_name: str = 'registry key') -> strnormalize_registry_key — Strip and `casefold a user-facing Registry key for case-insensitive lookup. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：str`。
参数
valuestrfield_namestr默认值 'registry key'返回值
class PostprocessingGuardrail(Protocol)PostprocessingGuardrail — Interface implemented by safety postprocessors such as face blurring. 属于 Core 基础能力（registry、通用工具、安全契约）。
方法
postprocess — Return safety-processed frames.
参数
framesnp.ndarray返回值
class PromptProcessor()简介
PromptProcessor — Apply optional prompt refiners and extenders without owning model loading. 属于 Core 基础能力（registry、通用工具、安全契约）。
源码 docstring
Apply optional prompt refiners and extenders without owning model loading.
`refiners rewrite a string or list in place; extenders take a {"prompt": ...} mapping and return an expanded dict. Both run under torch.no_grad()`.
方法
load_prompt_refiners — Instantiate each refiner with `from_model_manager(model_source)` and append it.
参数
model_sourcerefiner_classesSequence[type]默认值 ()返回值
load_prompt_extenders — Instantiate each extender with `from_model_manager(model_source)` and append it.
参数
model_sourceextender_classesSequence[type]默认值 ()返回值
process_prompt — Run refiners in order on one prompt or a list; lists are processed recursively.
参数
promptpositivebool默认值 True简介
extend_prompt — Wrap `prompt as {"prompt": ...}` and run extenders in order.
源码 docstring
Wrap `prompt as {"prompt": ...}` and run extenders in order.
`positive` is kept only to match the refiner API; this implementation does not use it.
参数
promptstrpositivebool默认值 Trueclass RegistryError()RegistryError — Base class for registry definition errors. 属于 Core 基础能力（registry、通用工具、安全契约）。
class RegistryItem(key: str,value: ItemT,aliases: tuple[str, ...] = (),metadata: Mapping[str, object] = <dict factory>)RegistryItem — One registered item plus its public aliases. 属于 Core 基础能力（registry、通用工具、安全契约）。
属性
keystrvalueItemTaliasestuple[str, ...]默认值 ()metadataMapping[str, object]默认值 <dict factory>def resize_and_letterbox(image,target_width: int,target_height: int,fill: tuple[int, int, int] = (255, 255, 255)) -> Image.Imageresize_and_letterbox — Fit an RGB image inside a fixed canvas while preserving aspect ratio. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：Image.Image。
参数
imagetarget_widthinttarget_heightintfilltuple[int, int, int]默认值 (255, 255, 255)返回值
def select_modality_statistics(dataset_statistics: Mapping[str, Any],modality: str = 'action',key: str | None = None) -> tuple[str | None, Mapping[str, Any]]简介
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'"action"`).keystr | None默认值 None返回值
(resolved_key, stats_mapping). *resolved_key* is None` when the input was already a direct statistics mapping.异常
KeyError- *key* is missing or has no *modality* mapping.
ValueError- Empty input, or multiple dataset keys with no *key*.
def set_random_seed(seed: int,by_rank: bool = False) -> int简介
set_random_seed — Set Python, NumPy, and PyTorch seeds with optional distributed-rank offset. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：int。
源码 docstring
Set Python, NumPy, and PyTorch seeds with optional distributed-rank offset.
Thin wrapper over :func:set_seed_everywhere (the canonical entry point). When the process group is unavailable, `by_rank` silently falls back to the unoffset seed.
参数
seedintby_rankbool默认值 False返回值
def split_horizontal_views(image,num_views: int,target_size: tuple[int, int] | None = None) -> list[Image.Image]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返回值
def stack_or_pad_tensors(values: Sequence[Tensor],padding_value: float | int | bool | None = None) -> Tensor简介
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返回值
class TypedRegistry(items: Iterable[RegistryItem[ItemT]] = ())简介
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.
参数
异常
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返回值
aliases — Return normalized alias to normalized canonical key mapping.
返回值
items — Return registry items sorted by their public key.
返回值
values — Return registered values sorted by public key.
返回值
class 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.ndarray简介
unnormalize_action_values — Convert normalized policy outputs back to environment-space actions. 属于 Core 基础能力（registry、通用工具、安全契约）。 标注返回类型：np.ndarray。
源码 docstring
Convert normalized policy outputs back to environment-space actions.
Inverse of :func:normalize_action_values for the same *mode* and *statistics*. Masked-off channels are copied through unchanged. Unlike the forward path, this function does not clip.
参数
normalized_valuesAnystatisticsMapping[str, Any]modestr默认值 'min_max'