Models and runners

WorldFoundry exposes two related extension boundaries. WorldModelRunner is the evaluation-facing protocol: it accepts normalized requests and returns normalized results. PipelineABC is the model-facing convenience layer: it owns loading and native inference behavior. An integration may implement both, or use an adapter between them.

WorldModelManifest

The public manifest is a compact DTO for model identity and capability. It is not the full catalog YAML and it is not runtime proof; it carries the fields that runner resolution and evaluation need after catalog loading.

class WorldModelManifest(model_id: str,name: str = '',aliases: tuple[str, ...] = (),version: str = '',provider: str = '',capabilities: tuple[str, ...] = (),supported_tasks: tuple[str, ...] = (),required_artifacts: tuple[str, ...] = (),output_artifacts: tuple[str, ...] = (),tags: tuple[str, ...] = (),metadata: Mapping[str, Any] = <dict factory>,schema_version: str = WORLD_MODEL_MANIFEST_SCHEMA_VERSION)

WorldModelConfig

WorldModelConfig is the construction payload passed to a runner. Put model-native knobs in parameters, execution placement or endpoint settings in runtime, and preserve the resolved public manifest when one is available.

from worldfoundry.evaluation.api import WorldModelConfig

config = WorldModelConfig(
    model_id="matrix-game-2",
    runner="worldfoundry.evaluation.models.runners.pipeline:WorldFoundryPipelineRunner",
    variant="matrix-game-2-universal-action-validation",
    parameters={"num_output_frames": 15, "fps": 12},
    runtime={"device": "cuda:0"},
    seed=42,
)

The target above is the current Matrix-Game 2 catalog binding. Runtime bindings can evolve, so production code should still resolve the current model manifest rather than hard-coding a documentation example.

class WorldModelConfig(model_id: str,runner: str,variant: str = '',parameters: Mapping[str, Any] = <dict factory>,runtime: Mapping[str, Any] = <dict factory>,seed: int | None = None,manifest: WorldModelManifest | None = None,metadata: Mapping[str, Any] = <dict factory>,schema_version: str = WORLD_MODEL_CONFIG_SCHEMA_VERSION)

WorldModelRunner

This runtime-checkable protocol is intentionally small. A local checkpoint class, hosted API client, simulator policy, or subprocess bridge can all satisfy it without sharing an inheritance hierarchy.

from worldfoundry.evaluation.api import GenerationResult, WorldModelRunner

class ExistingArtifactRunner:
    model_id = "existing-artifact"
    capabilities = {"video_generation"}

    @classmethod
    def from_config(cls, config):
        return cls()

    def generate(self, requests):
        return [
            GenerationResult(
                sample_id=request.sample_id,
                model_id=self.model_id,
                status="failed",
                error="No generation implementation was configured.",
            )
            for request in requests
        ]

    def cleanup(self):
        pass

assert isinstance(ExistingArtifactRunner(), WorldModelRunner)

The example returns explicit failures to demonstrate the contract; a real runner must materialize artifacts and populate them in each successful result.

class WorldModelRunner(Protocol)

PipelineABC

PipelineABC gives model integrations a shared loading and call shape while preserving native behavior. from_pretrained constructs components, process normalizes inputs, __call__ runs one inference, and stream exposes the same operation to interactive surfaces. Production pipelines may override any of these methods.

class PipelineABC(model_id: str | None = None,operators: Any = None,operator: Any = None,synthesis_model: Any = None,memory_module: Any = None,device: str = 'cuda',**kwargs: Any)

Which boundary should an integration implement?

Implement WorldModelRunner when the goal is benchmark execution, batching normalized samples, caching, or producing evaluation ledgers. Implement or subclass PipelineABC when the goal is a reusable model-native inference object for scripts or Studio. If both are needed, keep checkpoint loading and native calls in the pipeline, then let the runner/operator translate GenerationRequest into pipeline inputs and pipeline output into GenerationResult.

For a complete repository integration, API conformance is only one step. The add a model guide also covers catalog identity, assets, runtime binding, bounded validation, and documentation.