Generate Scene

When to Use

• User describes a scene in words and wants the generator to produce it (scene.usda + scene_info.json + layout graph).
• User has an LLM_RESULT.py (hand-written or LLM-produced) and wants to compile / preview it.
• User wants a quick one-shot scene without standing up Open WebUI / MCP — Claude writes the DSL program directly (Path B below).

Prerequisite only for Path A (the Open WebUI agent loop): the MCP stack + Open WebUI are running (deploy-generator first). Path B needs just the package importable + ASSETS_INDEX available — no servers.

Do not use for:

• Standing up the servers → deploy-generator skill.
• Just browsing assets → search-assets skill.

The pipeline (what actually happens)

NL request
  │  ── Path A: Open WebUI "geniesimscenegen" agent (uses search_assets/get_interactions)
  │  ── Path B: Claude writes the DSL program directly (no WebUI / no MCP server)
  ▼
Python program:  from helper import *  →  @register()… def root_scene() -> Shape
  │  written to → src/geniesim_generator/LLM_RESULT.py
  ▼
cd src/geniesim_generator && python app.py  (imports LLM_RESULT.root_scene, runs it)
  │  gen_scene_layout_info → (scene_info, networkx graph)
  │  gen_scene_usda        → scene.usda
  ▼
benchmark/config/llm_task/<scene_id>/<n>/{scene.usda, scene_info.json, graph.dot, graph.svg, LLM_RESULT.py}

The program is the only handoff between "write" and "compile" — so Path A and Path B differ only in who writes it. Path B (Claude writes it directly) needs neither Open WebUI nor the MCP servers running; it only needs the package importable and ASSETS_INDEX available.

Workflow

Step 1 — Produce LLM_RESULT.py from the request

Two ways; pick by whether the WebUI/MCP stack is up.

Path A — via the Open WebUI agent (the deployed loop)

Drive the geniesimscenegen agent (import config/geniesimscenegen.json; MCP tools wired via config/openwebui.json). Describe the scene; the agent searches the asset library, writes a DSL program, and its "save to file" action drops it at generator/LLM_RESULT.py. Requires deploy-generator first.

Path B — Claude writes the program directly (no WebUI, no MCP)

When the servers aren't up (or you just want a one-shot scene), write LLM_RESULT.py yourself and run the compiler. This is the lightweight path.

1. Get real asset ids. The program must reference ids that exist in ASSETS_INDEX — guessed ids raise KeyError in helper.usd(). Options:

   • If the MCP server is up, use the search-assets skill.

   • Otherwise query the index directly in Python:

     python -c "from geniesim_assets import ASSETS_INDEX; \
       import re; pat=re.compile('bottle', re.I); \
       print([k for k in ASSETS_INDEX if pat.search(k)][:20])"

2. Write the program to src/geniesim_generator/LLM_RESULT.py following the contract below. Build every object through usd(oid, keywords) / library_call("usd", …) and place with the DSL helpers (transform_shape, translation_matrix, rotation_matrix, attach, align_with_*, concat_shapes).

   Minimal real example (mirrors the shipped template):

   from helper import *
   
   @register()
   def place_bottle(oid: str, position) -> Shape:
       shape = library_call("usd", oid=oid, keywords=["bottle", "drink"])
       # drop it so its center lands on `position`
       center = get_object_info(shape)["center"]
       return transform_shape(shape, translation_matrix(np.array(position) - center))
   
   @register()
   def root_scene() -> Shape:                 # REQUIRED entry point — app.py imports this name
       a = place_bottle("genie_beverage_bottle_007", (-0.32, -0.96, 1.11))
       b = place_bottle("genie_beverage_bottle_008", (-0.32, -0.70, 1.11))
       return concat_shapes(a, b)

   Keep one @register() on each builder (the decorator pushes the layout stack frame gen_scene_layout_info walks) and exactly one root_scene().

3. Proceed to Step 2 to compile.

The program must follow the contract (see the shipped LLM_RESULT.py template):

from helper import *

@register()
def place_mug() -> Shape:
    ...                       # build from usd(asset_id) + transform/concat helpers

@register()
def root_scene() -> Shape:    # REQUIRED entry point — app.py imports this name
    return place_mug()

If the user supplies their own program, overwrite the live slot src/geniesim_generator/LLM_RESULT.py with it (back up the original first). This is the one reliable way to feed a program in — see the --template_path caveat in Step 2.