SDK (B2B2C)Frozen-DAG mode

Frozen-DAG mode

By default, the SDK does not run Pyodide in the partner browser. Pyodide + cadbuildr-foundation + a project wheel weighs ~10 MB and takes 8–15 s to cold-start on a mid-range phone — unacceptable for a storefront.

Instead, the partner ships two artifacts produced at project publish time:

  1. parameters.schema.json — the parameter list (see Parameter form).
  2. template.dag.json — the project’s DAG, but with parameter primitives replaced by ParameterInput placeholder nodes.

At runtime, the SDK substitutes the user’s current parameter values into the ParameterInput nodes and posts the finished DAG to kernel-api.

The ParameterInput node

A normal DAG node for an integer literal looks like:

{ "type": "IntLiteral", "value": 4 }

In a frozen template, the same slot becomes:

{ "type": "ParameterInput", "parameter": "n_layers", "fallback": 4 }

fallback is the project’s default value — used if the SDK cannot resolve the parameter (e.g. the form is uninitialized).

Substitution semantics

The substituter (substituteParameterInputs in @cadbuildr/sdk-react):

  • Walks the DAG depth-first.
  • Replaces every ParameterInput node with a primitive literal of the matching parameter’s runtime value.
  • Validates types: a Color parameter cannot fill an Int-shaped slot, etc. Type mismatches throw MissingParameterValueError.
  • Is pure — same (template, values) always produces the same output DAG. The kernel-api L2 cache keys on the resulting DAG, so the substitution must be deterministic.

You can call it yourself for advanced flows:

import { substituteParameterInputs } from "@cadbuildr/sdk-react";
 
const dag = substituteParameterInputs(template, {
  n_layers: 4,
  brick_color: "bright_red",
});

<CadbuildrViewer parameters={values}> does this for you when you hand it a template DAG.

When to fall back to Pyodide

The frozen-DAG path assumes the DAG’s topology doesn’t change with parameters. If your project does any of:

  • Conditionally adds / removes operations
  • Loops over a parameter (e.g. “generate n rings”)
  • Imports a kernel feature that doesn’t exist at every parameter value

…then the template DAG isn’t valid for all inputs. In those cases the partner opts into Pyodide:

<CadbuildrViewer mode="pyodide" pythonScript={projectScript} parameters={values} />

This loads @cadbuildr/cad-pyodide-runtime, fetches the wheel, runs your Python code, captures the DAG, and ships it to kernel-api. The trade-off is the cold-start hit — typically only worth it for partners who really need the full topology range.

Publishing the template + schema

The Python decorator’s emit_schemas() (or your build pipeline) writes both files to parameters/<project_id>.schema.json and parameters/<project_id>.template.dag.json. Host them somewhere the partner browser can fetch — your CDN, the kernel-api itself, or checked in next to your storefront.

A future release of CADbuildr will publish templates to a managed CDN automatically; until then, the partner is responsible for hosting and cache-busting them.

Parameter formCaching