Studio Internals

Studio is a catalog-driven shell over the same pipeline and artifact contracts used by CLI inference and evaluation. It does not own model weights, scoring logic, or benchmark manifests. Its job is to discover runnable entries, prepare inputs, invoke the right runtime driver, write a RunRecord, and pick preview assets for the UI. The same execution core can serve Gradio (app.py), Workspace jobs, conda child processes, and torchrun workers; only the presentation layer changes.

launch args
  -> StudioLaunchConfig
  -> discover_catalog()
  -> StudioManager
  -> prepare_inputs()
  -> runtime_driver_for()
  -> run()
  -> materialize_run()
  -> pick_preview_assets()
  -> Gradio / Workspace UI update

Keep inference semantics in studio/execution.py and catalog discovery in studio/catalog.py. studio/app.py should stay thin: layout, callbacks, and Gradio component updates. If a change must also work from runtime_job.py or workspace_app.py without Gradio, it belongs in execution, not in the UI file.

Files

Catalog Discovery

Catalog build is intentionally static. discover_catalog() walks pipeline modules with AST helpers so Studio can list models without importing heavy CUDA stacks or optional dependencies. It merges three sources: pipeline_*.py classes, component-pipeline factories, and action-synthesis classes, then overlays curated overrides and canonical runtime entries (aliases, default kwargs, checkpoints, runtime_kind). Dedup keys are (module_path, class_name). Hidden or abstract ids stay out of the UI list.

Import happens later, only when a run needs a concrete class: StudioManager.import_pipeline_class() loads module_path / class_name from the selected CatalogEntry. That split is why a model can appear in the catalog yet still fail at LOAD if the current environment lacks its runtime imports or local checkpoint.

Execution Core

StudioManager is the orchestration hub. A typical run / stream / init / reset path prepares a request, stages inputs into a run directory, selects a driver from entry.runtime_kind, loads the pipeline (LRU-cached), invokes the driver, then materializes a RunRecord. Drivers exist because not every family is a single __call__: two-stage 3DGS reconstructs then orbits, point-cloud nav reconstructs then renders views, WorldFM needs custom camera and panorama handling. Everything else uses BaseRuntimeDriver.

PreparedInputs is the normalized payload after staging prompts, images, videos, interactions, and runtime kwargs. PipelineContext holds the loaded class, device, variant, and output root. RunRecord is the durable unit the UI reloads: ids, inputs, outputs, artifact paths, preview picks, status, and manifest JSON. Workspace inference may also pass an infer_metadata contract so materialization can enforce required output kinds (video, image, splat, and so on).

Preview and Artifact Helpers

After the driver returns, materialize_run() turns a heterogeneous result into files under the run directory: metadata JSON, known artifact keys, optional frame-to-video export, mesh conversion, and optional Rerun recordings. When previews are still empty, Studio may scan the output directory depending on WORLDFOUNDRY_STUDIO_ARTIFACT_SCAN_MODE. pick_preview_assets() then ranks artifacts for the UI—preferring generated videos and named previews over staged inputs—and returns the primary video, image, splat/model, gallery, and optional .rrd.

Blank previews usually mean the pipeline wrote files outside expected keys, returned an in-memory object without save(), or produced a video the decoder rejects. Fix the pipeline contract first; only then widen scan mode or conversion helpers.

UI File Boundaries

Treat app.py as presentation glue. Launch flags that only affect Gradio stay there; values that change non-UI execution belong in StudioLaunchConfig consumption inside execution. HTML status blocks and tray cards stay in the UI. Button handlers may call StudioManager, but they should not load pipelines, stage files, or invent artifact layouts themselves. Presets that are purely demo defaults can live in the UI; presets that must match evaluation or Workspace contracts should be shared data, not Gradio-only strings.

Debug Path

Most Studio bugs are contract mismatches, not Gradio bugs. A missing model is almost always catalog discovery, aliases, or a hidden id. Wrong device or variant usually means launch config and PipelineContext overrides. Inputs that never reach the model fail in prepare_inputs() or driver kwargs binding. Streaming failures often mean init/stream was called without memory state or without a prior reconstruction for two-stage drivers. Recent-run reload failures mean the manifest or artifact paths drifted after materialize_run().

For end-user launch and frontend routing, see Studio. For the pipeline / operator / GenerationResult contract Studio sits on, see Model Runtime.