origami CAD: describe a force response, get back a verified fold pattern

This repository holds only work done during the Meta Global AI Developer Hackathon (from 2026-10-26, 11:00 America/Chicago). It builds on earlier code (the simulator, generators, world models, census and proposer v0/v0.5), which lives in a separate repository, origami-world-model-prior, and is fetched by scripts/setup_prior.sh (setup). What came before and what was built this week: below and HACKATHON.md.

A pipeline that designs origami-inspired programmable force-response metamaterials from natural language. These are folded cells whose force–displacement curve is designed: a flat force plateau over a set stroke, a click at a set travel, resistance in stages, or a set of shapes the cell holds by itself. They recover elastically, so the part can be used again. You type or say the curve you need, in your own words and numbers. Meta's Muse Spark turns that into precise checks and plans which fold-pattern families to try. The pipeline searches and tunes crease layouts across those families on a physics simulator. You get back a crease pattern whose behaviour the simulator has verified and stress-tested, with a datasheet saying how far each number can be trusted, or an honest "not found within budget".

• Project overview: docs/overview.md: what the pipeline does, what these metamaterials are, how engineers design them today, the bottlenecks, how the pipeline works, and next steps.
• Live app: https://raphaeldchen--origami-cad-web.us-east.modal.run/
• Designs from tonight's runs: Force-Response Designs: requests, 3D motion, force curves and crease patterns.
• Built for: Meta Global AI Developer Hackathon, theme "Push the Frontier" (Oct 26 – Nov 4, 2026).
• What was built during the hackathon, and what before: HACKATHON.md (summary below).
• The plan in plain language: docs/plan.md.

Example (live app, 2026-11-02, run r-e151c1ef). Request: "I want a pad that pushes back with the same force, about 5 N, from 20 % to 50 % of its travel, whatever the exact thickness of the part it clamps, and springs back fully when released." Muse Spark mapped it to force_plateau (window 0.2–0.5 of the stroke) and springs_back, and listed the 5 N as unchecked (forces are relative). The planner tried four families. A tiling layout met both checks robustly: 10 of 10 perturbed copies and 3 of 3 nudged runs, 57 simulator calls, 7 minutes and $0.02 of compute. "Verified" means verified by our simulator; forces in tiling layouts have not yet been checked against experiment.

At a glance

Question	Answer today (2026-11-02)
What does it design?	Force–displacement shapes (plateaus, clicks, staged and equal-force steps), multistable held shapes and heights, push–pull switching, stiffness switching and Poisson-programmed cores. All are quasi-static and elastic.
How often does it succeed?	On 8 force-response requests swept over 3 seeds, a planned run returned a robust, simulator-verified design in 17 of 24 runs at 120 simulator calls, and 17 of 24 at 360 calls (sweep).
Does it design new crease layouts?	It searches 8 families at once. These include tilings and mixed-vertex sheets outside the standard catalog, plus Kresling towers where a known family suffices. It composes and tunes layouts within those families' grammars, and doesn't claim new pattern classes.
Who decides that a design works?	The physics simulator, always, including a robustness test: refined run, 3 nudged runs, 8 of 10 perturbed copies. Muse Spark translates, plans and explains, but never grades a result.
How far can the numbers be trusted?	The Kresling family is validated against experiment (Zang et al., PNAS 2025). Other families agree with theory or are not yet validated, and the datasheet tags each. Forces are relative; newton units are validated on framed Kresling but not yet live.
Is the learned world model in the search loop?	No, not yet. No world model has passed its held-out gates on grids (see The world model). The search runs on the simulator alone, and the app's pipeline strip says "skipped".
Can I download the pattern?	Yes: FOLD v1.2 and an SVG cut-and-score file, but only for simulator-verified designs.
Has it been folded in real paper?	Not yet. A bench protocol for paper stiffness is prepared; no CAD design has been folded and measured.

Why it matters

Force-response metamaterials get their behaviour from geometry rather than from the material. A folded paper cell can hold a part at constant force, give a gloved finger a click, or count presses without electronics. Engineers specify the curve they want, but designing a fold pattern that delivers it is still done by hand:

• The pattern is chosen before the search. Most origami engineering "is based on an adaptation of existing origami patterns", and inverse design for engineering targets is "still in the rudimentary stages" (Misseroni et al. 2024). Recent inverse-design work maps a target force curve to geometry within one fixed family. When a target is out of that family's reach, the engineer has to pick another family by hand.
• Standard patterns often fall short. In a census of 200 origami-engineering papers (118 read in full), 35 % said a standard fold pattern could not deliver what they needed, and 28 % changed the crease topology by hand (census results).
• Robustness goes untested. Snap-through designs sit on knife edges. In our own tests, 33 of 35 designs that passed a lock-and-reopen test changed behaviour when nudged by one part in ten thousand (docs/plan.md).

We found no tool, commercial or academic, that takes mechanical requirements in plain language and returns a verified, robustness-checked pattern across several families. The pipeline does that. The full argument is in docs/overview.md.

How it works

 request, typed or spoken
   │  Muse Voice Transcribe (spoken requests)
   ▼
 Muse Spark: translation ──► checks: a template + slots, each quoting the words it came from;
   │                         asks when a threshold is missing; refuses what the simulator can't check
   ▼
 runner: new-layout generators first ──► probe every generator, then concentrate the budget
   │                                     (successive halving; Muse Spark can reallocate each round)
   ▼
 [world-model screen: skipped, no model passes its gates]
   ▼
 simulator, fanned out on Modal ──► pass rules (benchmark v3 amendment I) + 5% strain cap
   ▼
 robustness clause: 10 perturbed copies (≥ 8 must pass) + 3 nudged runs
   ▼
 verdict + datasheet (every number badged and linked to its simulator run)
   │  exports (FOLD, SVG) only for a verified design
   ▼
 paper test: fold it, film it, SAM 3.1 measures it (plan 07, in progress)

Each stage was built from its own plan; all are in docs/plans/. The index is 2026-10-27-cad-impl-00-index.md.

Stage	Plan	Code	Status
Pipeline core: contracts, generators, check templates, runner, verdicts, exports	01	src/origami_wm/cad/	Merged, PR #63; runner speed-up PR #71
Pass rules for new layouts (benchmark v3 amendment I)	02	src/origami_wm/specs/, cad/templates_g.py	Merged, PR #62
Serverless fan-out and the run API	03	cad/serve/	Merged and deployed, PR #69
Muse Spark design agent	04	cad/agent/	Merged, PR #67
Web app	05	cad/web/	Merged and deployed, PR #75
Request suite and capability sweep	06	—	In progress (results Oct 31)
SAM 3.1 paper test	07	—	In progress

1. Muse Spark translates the request (plan 04)

Muse Spark (muse-spark-1.3, pinned) works as a tool-calling agent. It never writes crease coordinates and never judges success. It may propose a generator's parameters, or a topology plan in a fixed language, which code turns into a certified pattern or rejects. Its jobs are below.

• Translate. It maps the request to one or more check templates and fills their slots (a count, an order, a tolerance). Each slot quotes the words it came from, so the judge sees, for example, "make the band farthest from me fold first" next to region_order, order = [1, 0]. Deterministic code assembles the check, so a check is always well formed. Every default is recorded.
• Ask, don't guess. A count or an order counts as stated only when the request's own words say it; otherwise Spark asks.
• Refuse. Requests the simulator cannot check, such as surviving a drop or an aluminium sheet, get a refusal with the reason, quoting the words it could not map.
• Allocate. After the probe, Spark can move simulator budget between generators each round, with a reason. If Spark is slow or unreachable, the round falls back to successive halving and says so.
• Plan the topology (always on in the app when the service has the planner, owner 2026-11-03; a request no plan family can test runs on the generator library; plan). Spark writes 2–4 topology plans a round in a fixed language (Dieleman class maps by region, pop-through sites, crease removals and additions, or Kresling towers), each with its rationale, shown as "Spark's reasoning, not verified". Code realises each plan as a generator or rejects it with the reason, TPE tunes its geometry and the simulator verifies, over up to 3 rounds of 40 calls. Under every planned run the page states what the A/B test against random plans (G-T1) found, and claims nothing before that verdict is in.
• Explain. The narration is grounded: every number in it comes from a tool output and links to its simulator runs. When Spark's text does not ground, a code-written summary replaces it.
• Follow-ups. Spark answers questions about a finished run, and may start one known-family comparison run.
• Voice. Spoken requests go through Muse Voice Transcribe. The transcript is shown for editing before translation.

Development numbers on 8 seed requests, 3 runs each: 7 of 8 translated exactly in all 3 runs, typed or spoken; every refusal and every question was right (plan 04 results). These are not design success rates. Translation accuracy on the held-out request suite: [pending: plan 06].

2. New layouts first: probe, then concentrate (plan 01)

• Generators emit only valid patterns. "Valid" means foldable from one real sheet: developable, mountain/valley consistent, and simulator-verified with peak panel strain under a cap (2% at the made state for compliant layouts; the pass rules add 5% over the whole push). Each pattern is tagged rigid or compliant.
• The live budget goes to new layouts: tiling (Dieleman tilings), tiling_stack and compliant. Known families (miura, graded, degree4, kresling) run only from the "Compare with known families" button or as a fallback (cad/registry.py).
• Probe, then concentrate. Each generator gets a small probe. The rest of the budget then goes, in rounds, to the generators whose best margin came closest to passing. This is successive halving (Jamieson & Talwalkar 2016), with a floor so slow starters are not cut too early (Hyperband). Within a generator, Optuna searches the geometry (cad/runner.py).
• A run ends at the first robust pass or when the simulator-call budget runs out, never on a clock.

3. The pass rules (plan 02, benchmark v3 amendment I)

What counts as a pass is fixed before any search uses it, and is never tuned:

• Parametric checks with calibrated ranges. A check's parameters are calibrated on positive and negative controls. Outside the range the check still runs, and the datasheet says "outside calibrated range". Checks with no known positive control (such as region_order) carry that warning on the datasheet.
• One push protocol for every sheet family, tilings included, so force and order checks can test new layouts.
• The robustness clause on every check. Load steps are doubled, and 3 nudged runs follow. 10 copies are built with crease stiffness × U(0.8, 1.2), pattern angles ±1° and rest angles ±2°, and at least 8 of 10 must pass.
• A 5% peak panel-strain cap over the whole protocol, and screens for degenerate passes (an unloaded sheet, a rest state that never moved).

The pre-registration and its control results are in docs/plans/2026-10-26-benchmark-v3.md (amendment I).

4. Serverless fan-out on Modal (plan 03)

• The simulator runs in a Modal container. A batch's simulator jobs, and a robustness check's 14 runs, fan out across cores in parallel.
• A FastAPI service exposes POST /runs, GET /runs/{id}/events (server-sent events) and GET /runs/{id}.
• Identical requests are served from cache and labelled as cached, with their date. Every result has a shareable ?run= link.
• Limits: 3 runs per visitor per hour and a hard spend cap.
• Checked against the laptop. The container's results match the laptop's on 6 of 6 designs, and it reproduces Zang et al.'s Kresling transitions on 55 of 56, as the laptop does (plan 03).
• Generators that reject most random draws used to need dozens of round trips; the runner now draws ahead for them (46 to 6 round trips on a live run, PR #71).

5. The web app (plan 05)

The layout is a CAD layout, in four regions:

• Design intent. The request, the derived checks as editable rows, and the sheet and loading fields. The material is locked to the simulator's one material, and the screen says so.
• Canvas. The crease pattern and the folded shape.
• Datasheet. Every property carries a badge: SIM-VERIFIED, PREDICTED, PENDING or MEASURED IN PAPER. It also shows the robustness result (k of 10 copies), peak strain, simulator calls, the verdict and a known-family comparison row.
• Pipeline strip. Generate → world model → simulate → robustness, with live counts and a funnel board of every simulated candidate. Muse Spark's narration runs in a side rail.

A capabilities panel shows which behaviours it can check and the measured success rate of each, with sample size and a 95% Wilson interval. Until plan 06's sweep lands, it says "success rate: not measured yet".

Before and after the request (2026-11-03):

• How it works. The compose screen opens with four steps (describe, confirm Spark's checks, a 10–25 min planned run, the verdict and files or "no robust design found") and points to the sidebar's verified designs for an instant finished result. It can be dismissed, once per browser.
• Odds on the confirm screen. Each check shows its category's rate in the overnight batch run of 2026-11-03 (for example "plateaus: 14 of 14 robust"), and the request shows its lowest, stated as an estimate from that batch, never a prediction of the run. The table, its source and the template-to-category map are one file, cad/web/static/odds.json.
• Generate a request (likely-to-succeed mode only). Code picks a behaviour from the batch's best categories (plateaus, push–pull, Poisson: 23 of 24 robust), values inside each check's calibrated band and a use case; one Muse Spark call writes the sentence (POST /agent/generate, cad/agent/generate.py), or a fixed template does, labelled so. The pipeline is never told: the text is translated, confirmed and run like a typed one, and the confirm screen shows any value translation lost next to the generator's. The request carries the label "GENERATED · likely-to-succeed mode · …" in the intent column, on the datasheet and on a shared link (the run's meta keeps the origin and the generator's record, outside the cache key), and "How was this picked?" shows the category, the ranges, the odds and the exact prompt. No sentence may repeat a suite request (tested against both request files).
• The live tally (GET /tally): this deploy's finished runs by origin, generated or typed, and how many were robust, shown next to the generator and on the result beside the batch's figures.

6. The paper test with SAM 3.1 (plan 07, in progress)

The user uploads a short side-view video of the hand-folded part. SAM 3.1 (through the Meta Model API) segments the sheet in each frame. The app finds the rest frames and compares each rest shape's profile with the simulator's prediction from the same viewpoint. The results are labelled MEASURED IN PAPER, apart from simulator-verified, and are qualitative: paper creases are pseudo-plastic, so the test compares shapes and rest angles, not forces. [pending: plan 07; the first paper fold is not done yet]

The world model: not in the loop yet

The project's long-term engine is a learned forward world model: crease pattern, material and loading in; behaviour and properties out, fast enough to screen thousands of new layouts. It is the part that lets the search scale beyond what the simulator can afford.

Where it stands, honestly:

• It passes on single degree-4 vertices it never trained on. Stable states and force beat the baselines.
• It fails on 2×2 and 3×3 grids of those vertices, where it predicts false stable states. Retraining on its own mistakes, labelled by the simulator, is under way (energy-model pilots, PRs #61, #66, #76).
• So the CAD's world-model stage is skipped. Every run reports "world_model": "skipped: …", and the app shows it.
• Simulator calls per verified design: without the world model, [pending: plan 06]. With it: not measured, because no model passes its gates.

Honesty rules

These are enforced in code and tests, not just stated:

• The simulator is the only verifier. A world-model prediction is never reported as verified, and Muse Spark never grades. Pass or fail comes only from the check code.
• "Designed" is kept apart from "needed".
  • "New layout designed" means a new layout passed robustly.
  • "A new pattern was needed" is a stronger claim. It is made only with evidence that known families fail: a benchmark result, or the comparison run failing at 60 or more clean simulator calls per family (cad/verdict.py, MIN_COMPARISON_CALLS).
  • The UI withholds any narration that says "needed" under any other verdict.
• Exports only for verified designs. FOLD and SVG files are written only for a simulator-verified design (cad/export.py, export_verified). The closest design under any other verdict gets no pattern file.
• Every number is traceable. Each margin, count and narration figure carries the ids of the simulator runs behind it.
• "Ran" is reported apart from "passed", and every success rate comes with its sample size and a 95% Wilson interval.
• No search starts from a known answer, and nothing that decides a pass is tuned after seeing results.
• Limits are stated. Forces and stiffnesses are in model units. The simulator is quasi-static bar-and-hinge with MERLIN's physics and contact: no dynamics, plasticity or sheet thickness.

Measured results

Behaviour	Requests (held out)	Runs: ran / passed	Success rate (95% Wilson)	Verified design is a new layout	Median time	Known families on this check
[pending: plan 06 sweep, Oct 31]

Simulator calls per verified design: without the world model [pending]; with it, not measured (no model passes its gates).

Measured so far:

• Live app, typed request, region_order: new layout designed, robust 10 of 10, 29 calls, 5 min 11 s (run r-732c99b5, above).
• Local service, typed request, region_order: new layout designed, robust 9 of 10, 17 calls, 80 s (run r-1f4bb806). The known-family comparison, 24 calls, found no known family passing. That is too few calls to claim a new pattern was needed, and the app did not claim it.
• Local, spoken request, "It should hold three different shapes after I let go": no new layout within budget after 24 calls. The closest design came from tiling, worst margin −0.503 (run r-0a0572c1). Honest failures are part of the product.
• The simulator itself reproduces Zang et al.'s Kresling transitions (PNAS 2025, DOI 10.1073/pnas.2426790122) on 55 of 56 moves. Forces run about 1.3× high, so they are labelled estimates. Beyond Kresling's transitions, its mechanics checks are partial: Miura pop-through holds only at bend ratios up to 10 (paper is about 36), single vertices are checked against rigid-panel theory rather than a real sheet, contact forces failed their one check, and on a Kresling cell the default physics (v1) is 2.6–3.9× stiffer than an independent shell FE. The classes the live search uses (tilings, stacks, compliant layouts) have exact kinematics but no mechanics check against published results; the one related reference run so far (the square twist's bistability) failed as registered. The live tiling-stack hit is material-sensitive; tiling 0's region_order holds across paper's material range in simulation. Details and the plan to close the gaps are in the validation matrix (§0, §9.7).

Meta models used

Model	Where	What it does
Muse Spark (muse-spark-1.3)	cad/agent/	A tool-calling agent. It translates the request into checks, asks or refuses, reallocates simulator budget between generators each round, writes topology plans when the planner is switched on, and narrates grounded results. It answers follow-up questions about a run and can start a known-family comparison.
Muse Voice Transcribe (muse-voice-transcribe-1.0)	cad/agent/, cad/web/static/js/voice.js	Spoken requests. The browser converts the recording to 16 kHz mono WAV, and the transcript is editable before translation.
SAM 3.1	plan 07 (in progress)	Segments the hand-folded paper part in each video frame, to compare its rest shapes with the simulator's.

All three are called through the Meta Model API (https://api.meta.ai/v1). The key is read from the environment or .env, never committed.

Run it locally

You need Python 3.13 or later, git, rsync, and Node.js for the front-end tests.

This repository depends on the pre-hackathon code in origami-world-model-prior, pinned at 7c6b49f1. Fetch it first; the script clones it into .prior/, applies the hackathon's edits to 33 prior files (prior-patches/event-edits-to-prior-files.patch), and lays the prior files into the working tree (never committed here: they are listed in .git/info/exclude):

git clone https://github.com/raphaeldchen/origami-cad-hackathon.git
cd origami-cad-hackathon
bash scripts/setup_prior.sh
python3.13 -m venv .venv
.venv/bin/pip install -e '.[dev,cad,serve]'
make test                      # Python tests, plus the web app's tests (node --test)

One design request from the command line (the real simulator, on your machine; no API key needed):

cat > request.json <<'EOF'
{"text": "Push on the sheet and make the band farthest from me fold first.",
 "checks": [{"template": "region_order", "params": {"order": [1, 0]},
             "source_phrase": "make the band farthest from me fold first"}],
 "budget_calls": 40, "seed": 0, "novelty": "new"}
EOF
nice -n 10 .venv/bin/python -m origami_wm.cad.run request.json --out runs/demo

runs/demo/ gets events.jsonl (the live event stream), result.json (the verdict, margins, robustness and simulator run ids) and, only if the design is verified, pattern.fold and pattern.svg. Templates are listed in src/origami_wm/cad/templates.py and src/origami_wm/specs/templates_g.py. Use "novelty": "known" to search the known families instead.

The web app and run API on http://127.0.0.1:8000, with a local process pool in place of Modal:

.venv/bin/python -m origami_wm.cad.serve --workers 4

Muse Spark and Voice need META_API_KEY in .env (see .env.example). Without a key, the agent routes answer 503, and you can still run checks directly through POST /runs.

The agent from the command line (needs the key):

.venv/bin/python -m origami_wm.cad.agent "It should hold three different shapes after I let go." --out runs/agent

Deploying to Modal (scripts/deploy_cad.sh) needs the owner's Modal workspace and a Modal secret named meta-api. The research tools from before the hackathon (dataset generation, world-model training and evaluation, benchmarks) are listed in CLAUDE.md §4 (a prior file, laid in by the setup script).

Built during the hackathon, and before

The hackathon started on 2026-10-26 at 11:00 America/Chicago. This repository was created afterwards and holds only work committed after that moment, with its original commit times. Prior work is in origami-world-model-prior: its hackathon-start tag (fac6afe) is the last commit before the start, and its main adds the three branches whose commits all predate the start (Phase 0b, benchmark v3 calibration, the energy-model pilot) and the code ported from Pleatwright.

How the split was made: every path that existed in any prior commit, and the 20 files ported from Pleatwright, were removed from this repository's whole history (git filter-repo). No file version in this history matches any file version in the prior repository. The hackathon's edits to 33 prior files are kept as a patch in prior-patches/.

Before (prior work):

• the bar-and-hinge simulator and its validation against Zang et al. 2025;
• the Kresling, Miura and degree-4 generators and the dataset generator;
• world models v1 to v2 and the energy-model pilot;
• the 200-paper census;
• proposer v0 and v0.5 (Dieleman tilings, requirement specs, compliant and stacking moves);
• benchmark v3's plan.

During the hackathon (one entry file per PR in hackathon/entries/, table in HACKATHON.md):

• the whole CAD:
  • pipeline core (#63) and runner speed-up (#71);
  • amendment I pass rules (#62);
  • Muse Spark agent (#67);
  • Modal service (#69);
  • web app (#75);
• benchmark v3 Part 2 and amendments F–J (#57, #58, #62, #64);
• new generators and labels:
  • zipper tubes and graded Miura (#53);
  • stowage label and protocol (#56, #60);
  • flat-foldable layer orders and a marching sampler (#74);
• world-model work: energy-model fixes and concurrent learning (#61, #66, #76);
• the simulator: a membrane-element study (#70) and a validation matrix (#77).

The video and the app show only hackathon work. The prior parts appear once, as "built on".

Repository layout

src/origami_wm/
  sim/          bar-and-hinge simulator (MERLIN physics, contact)          prior work (prior repo), extended by the patch
  generators/   Kresling, Miura, degree-4, graded Miura, zipper tubes, square twist
  proposer/     new layouts: Dieleman tilings, compliant and stacking moves, flat-fold certification
  specs/        requirements, protocols, amendment I's parametric checks and calibrated ranges
  bench_v3/     benchmark v3 arms and controls
  data/, wm/    dataset format and the world models (not in the CAD loop yet)
  cad/          the CAD: schema, registry, templates, runner, verdicts, export
    agent/      Muse Spark: translation, allocation, grounded narration, voice
    serve/      run API, Modal app, fan-out, limits
    web/        the web app
docs/plans/     every plan, with pre-registrations and results
docs/research/  census, prior-art notes, market research
hackathon/      one log entry per hackathon PR
prior-patches/  the hackathon's edits to 33 prior files, applied by scripts/setup_prior.sh

Licence and related work

Apache-2.0 (LICENSE, NOTICE). Code ported from the author's earlier project, Pleatwright (the box-pleat pipeline in proposer/pleat/ and the layer certifier in proposer/certify/), is pre-existing code, so it lives in the prior repository, marked in each file; this repository holds only the code that wires it in. Prior art for every part is cited in its plan (CLAUDE.md §0). The demo design's survey is in §9 of the demo spec.