Gap

graph-as-policy — GaP

GaP compiles robot tasks into typed, verified skill graphs and executes them. The policy is the graph: nodes call tools (perception models, planners, robot motions) or run skill scripts; postcondition checkpoints verify progress against the simulator state. Two kinds of repos exist:

• the engine (graph-as-policy, imports as gap) — CLI, runtime, builder, codegen, connectors (LIBERO sim / real Franka & UR);
• skill registries — directories of bundles (skills/<name>/SKILL.md strategies, tools/<name>/SKILL.md model-backed tools). open-robot-skills is the canonical public registry, normally cloned side-by-side with the engine and auto-discovered. Any number of registries layer by precedence.

Ground truth: gap <command> --help is authoritative; references/cli.md here is a generated snapshot. When working inside a checkout, prefer its docs/ (design.md, runtime.md, skills.md, safety.md) over the digests in this skill.

SAFETY — standing rules

• NEVER run gap run --real ... or gap.connector.real(...) unless the human has explicitly confirmed that specific run in this conversation. Real-robot work requires a human with the E-stop in hand and docs/safety.md read. Do not weaken this gate, ever.
• Sim-first, always: validate (gap run <graph> --validate-only), then sim (--sim), and only then discuss real hardware.
• Use --checkpoints raise on anything real; warn (the default) in sim.
• Never claim a task succeeded without evidence: checkpoint pass in the trace, sim.check_success, or gap benchmark --gate.
• Never commit API keys or tokens; set them as env vars.

0. Bootstrap / install check

Always start by finding out what exists and what can run:

uv run gap check            # inside a checkout (or just `gap check` if on PATH)
gap check --format json     # machine-readable; parse this when deciding

If the CLI is missing, set up from scratch (Linux; GPU needed for sim):

git clone --recurse-submodules https://github.com/graph-robots/graph-as-policy.git
git clone https://github.com/graph-robots/open-robot-skills.git   # side-by-side
cd graph-as-policy
uv sync --extra quickstart        # engine + sim + sam3/grounding-dino/geometry
uv run gap skills check --download   # verify bundles + prefetch model weights

Gotchas: cloning without --recurse-submodules breaks uv sync ("does not appear to be a Python project") — run git submodule update --init; --extra grocery|all need CUDA_HOME set (cuRobo compiles CUDA at install); sim runs want MUJOCO_GL=egl.

Env vars that matter: OPENROUTER_API_KEY (default codegen provider) / Vertex via gcloud ADC + GOOGLE_CLOUD_PROJECT; GAP_LLM_PROVIDER + GAP_LLM_MODEL pin a non-default provider per shell (vertex also needs uv run --extra vertex); GAP_SKILLS_PATH (colon-separated registry roots); HF_TOKEN (gated weights); GAP_LLM_CACHE_DIR, GAP_LLM_NO_CACHE.

1. Discover what the robot can do

gap registry list                      # active registries, precedence order
gap skills list                        # every bundle (skills + tools) + registry
gap skills table --format markdown     # paste-ready catalog
gap tools list                         # flat tool catalog with live schemas
gap tools show geometry.compute_obb    # full input/output schema + runnability
gap check                              # what is operational HERE + fix hints

gap check is the decision input: a bundle is READY (deps importable, declared GPU/env requirements met) or NOT READY with a fix hint; each skill is READY or BLOCKED by the tool bundles it needs. Apply the fix hints (uv sync --extra X, export KEY=...) before attempting tasks that need those bundles. Resolution precedence for registries: --skills flags > $GAP_SKILLS_PATH > project pyproject [tool.gap].registries > ~/.config/gap/registries.toml > the side-by-side open-robot-skills checkout. Details: references/registries.md.

2. Run an existing graph in sim

MUJOCO_GL=egl uv run gap run examples/libero_quickstart/graph \
    --sim libero_object/0 --checkpoints warn

• --validate-only first when in doubt — structural validation without a robot.
• --inputs key=value binds top-level workflow inputs.
• --record-video (sim only) saves <trace-dir>/run_video.mp4 of the run.
• Every run writes a trace (dag_trace.json + per-node assets) under --trace-dir (default outputs/run_<timestamp>). Read it for node inputs/outputs, checkpoint results, and failures.
• gap viz serves an interactive trial browser at localhost:9432.
• The repo's examples/ each have a README: libero_quickstart (start here), grocery_fulfillment (benchmark-gated), steered_policy, collect_and_train, cable_ur, real_franka_pick_place.

Programmatic equivalent:

import gap
conn = gap.connector.sim("libero", task="libero_object/0")
result = gap.execute("examples/libero_quickstart/graph", conn,
                     checkpoints="warn")
print(result.success, result.exit_status, result.trace_path)

3. Compile a graph from language

When this skill is running inside Claude Code, you are the codegen pipeline — do NOT call gap generate. Turning a task into a graph is a §4 hand-authoring job: read the task, pick skills from the active registries, build the nodes with gap.builder, attach checkpoints, and drive gap run --validate-only to a clean pass. You are a stronger model than the one gap generate would dispatch to, and you stay in the loop to fix validation errors — so author directly, don't shell out.

gap generate is the headless path: benchmark grids, cron, or gap.agent.generate_sync() called from code — any run with no interactive model present. It dispatches a coordinator → per-subgraph → checkpoint pipeline to the configured provider's API (--provider/--model; see gap check for what's configured). Reach for it only when there is no Claude in the loop.

# headless only — NOT the path to use from inside Claude Code:
uv run gap generate "pick up the alphabet soup and put it in the basket" \
    --provider openrouter --out outputs/soup