Surfaces and orchestration

What this layer is for

TUI, CLI, Studio, Python, and MCP are different ways to operate the same system. None of them owns model inference or benchmark scoring. Their job is to turn user intent into one of the request types the execution layer already understands, and to surface the results. This page covers CLI/TUI, a pointer to Studio, MCP, and the orchestration service that compiles intent into a runnable plan.

Read Workflow first for where these paths land once a request exists. Read Evaluation core for the delegate runners that actually execute.

CLI and TUI

The console entry is worldfoundry/cli/main.py:1888 main(). It builds a subcommand tree starting at cli/main.py:1088:

• tui — launches the guided-discovery TUI. The TUI lives in cli/tui.py (main at :131) with its app, discovery, brand, and icon helpers in the cli/tui_*.py files. It drives the same catalog and orchestration calls as the CLI; it is presentation, not a second runtime.
• evaluate — normalizes inputs, picks a run mode, returns one EvaluateRunResult.
• run — model run: resolves a model runner, generates, then scores.
• validate — validates benchmark metadata loading without running a model.
• embodied — embodied eval subtree (run, serve, merge, plan).
• Plus zoo, preflight, dataset, tasks, reporting, model_run, plan_metric, mcp helpers.

The CLI dispatches into the orchestration service; it does not import pipeline files or compute metrics directly. Keeping it this way is why a new surface can be added without re-implementing generation, artifact materialization, or scoring.

Studio is the interactive preview surface. Its install/entry is worldfoundry/studio/cli.py:78 main(). It uses the same catalog and runtime contracts; it does not own scoring. Internals live on Studio internals.

MCP

The MCP server exposes the catalog, run lifecycle, metrics, and readiness as tools so an agent can drive the same workflow. It is a thin shell over the same contracts; it contains no private model code.

• Entry: mcp/__init__.py:30 main(); server construction in mcp/server.py (create_mcp_server :38, run_server :55).
• Tools are registered through mcp/tools/registration.py:55 register_tools, which binds each payload as an @mcp.tool().
• Tool payloads are grouped by responsibility, not by model: discovery (list/get model, benchmark, task), runs (preview, evaluate, status, result, samples, cancel), metrics (list, show), readiness (benchmark dataset checks), studio (workspace inference), and context (MCPToolContext).

Because every tool resolves through the same catalog and orchestration service, an MCP-driven run and a CLI-driven run produce the same artifacts and scorecards.

Orchestration service

The orchestration service is the single compile boundary between a surface and execution. It lives in evaluation/tasks/execution/orchestration/service.py. It validates one of five intent dataclasses and returns a PreparedEvaluation that the execution layer can run.

Each intent has a matching _prepare_* function (service.py:414–:642). The public entry points are prepare_evaluation(intent) at service.py:737 and execute_prepared_evaluation(prepared) at service.py:753. A surface's job is to produce one of these intents; it must not duplicate generation, dispatch, or metric execution.

The three planning boundaries

WorldFoundry keeps three planning types distinct. Do not wrap them in a fourth recipe executor.

A caller flag can only narrow the claim level, never promote a diagnostic run to an official one. score_valid records whether the evaluator produced a usable score; leaderboard_valid additionally requires comparable provenance and benchmark-runner evidence. See Evaluation core for how claim level flows into the scorecard.

For the directory-level map, see Codebase map. For the execution side these surfaces hand off to, see Workflow.