ChoreoForge

Expert feedback → typed motion constraints → bounded Codex task → regression evidence

ChoreoForge is a Developer Tool for humanoid-motion teams. It turns corrections such as “keep the support feet flat” or “stop the opening arm from clipping through the torso” into a strict motion specification, measurable evals, staged curriculum, and reviewable engineering task.

The sample path is deterministic and runs on a CPU without an OpenAI API key, robot, GPU, GR00T, or Isaac Lab. Live mode optionally uses GPT‑5.6 through the OpenAI Responses API with Pydantic Structured Outputs.

Quick demo

Requires Python 3.11 or newer.

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
./scripts/run_demo.sh

Open http://127.0.0.1:8000. The default sample runs immediately. Use the three presets to inspect exact sanitized case-study evidence.

Static judge demo

source .venv/bin/activate
./scripts/run_static_demo.sh

Open http://127.0.0.1:8080. static_demo/ has no backend dependency and makes no API request, so it can also be published directly with GitHub Pages.

Live GPT‑5.6 mode

export OPENAI_API_KEY='...'
export CHOREOFORGE_MODEL='gpt-5.6-terra'
./scripts/run_demo.sh

Enable Live GPT‑5.6 in the UI. The key stays server-side. Live requirements are rendered next to clearly labeled, precomputed case-study evidence; the application never implies that GPT generated or validated that evidence.

The live implementation follows this typed Responses API path:

response = client.responses.parse(
    model=os.getenv("CHOREOFORGE_MODEL", "gpt-5.6-terra"),
    input=[...],
    text_format=MotionFeedbackSpec,
)

Without a key, live mode fails clearly while sample mode remains fully operational. This checkout validates the live request contract with a mocked SDK response; a real API smoke test requires model access on the deploying account.

What it produces

Every analysis returns:

• a strict MotionFeedbackSpec with affected segments, constraints, units, verification methods, calibration state, safety gates, curriculum, and limitations;
• a bounded CODEX_TASK.md with an allowlist, measurable acceptance gates, prohibited shortcuts, and required proof;
• an eval_spec.yaml contract;
• a machine-readable constraint_spec.json;
• before/after metrics with explicit provenance and validation scope.

Representative checked-in exports live in outputs/. The UI generates all three downloads for the selected case.

Real sanitized case-study evidence

All evidence is labeled Precomputed evidence, No live API call in sample mode, and Kinematic validation only.

Case	Before	After	Result
Elbow-clearance proxy	−12.1 cm	+4.3 cm	pass
Wrist-clearance proxy	−4.6 cm	+7.5 cm	pass
Visible judges’ bow	14°	29.44°	pass with joint-limit warning

Contact-foot tilt p95 after the flat-feet change:

Robot / foot	p95
male left	0.16°
male right	0.24°
female left	0.08°
female right	0.07°

These are kinematic metrics from a sanitized dual-humanoid waltz workflow. They are not rigid-body, actuator, contact-force, or real-robot results.

Architecture

Browser
  ├─ sample mode ── deterministic local case engine
  └─ live mode ──── FastAPI ── Responses API + MotionFeedbackSpec
                              │
Typed specification ──────────┼─ CODEX_TASK.md renderer
                              ├─ eval_spec.yaml renderer
                              └─ constraint_spec.json renderer

Precomputed evidence ─────────── separately labeled evidence panel

FastAPI exposes:

• GET /healthz
• GET /api/cases
• POST /api/analyze
• / and /static/* for the product UI

See docs/ARCHITECTURE.md for trust boundaries and data flow.

Test and verify

source .venv/bin/activate
./scripts/test.sh

The script runs:

python -m pytest
python -m ruff check .
python -m compileall -q choreoforge

Tests cover schemas, deterministic sample selection, API behavior, mocked live Structured Outputs, task rendering, eval rendering, exact metrics, and static assets.

Docker

docker build -t choreoforge .
docker run --rm -p 8000:8000 choreoforge
curl -f http://127.0.0.1:8000/healthz

The image runs as the non-root appuser and includes a health check. A hardened Compose path is also available:

docker compose up --build

Compose uses a read-only root filesystem, drops Linux capabilities, and enables no-new-privileges.

Build Week scope and Codex collaboration

The dual-Unitree-G1 waltz research and its GR00T/SONIC environment predate this project. ChoreoForge is a new, isolated product layer built for OpenAI Build Week. It does not modify or redistribute the original robotics repository, checkpoints, datasets, or robot assets.

• BUILD_WEEK_SCOPE.md separates prior work from the submitted extension.
• docs/CODEX_COLLABORATION.md records the primary Codex session, concrete implementation work, human-owned decisions, rejected shortcuts, and verification.
• DEVPOST.md contains submission-ready copy.
• docs/DEMO_SCRIPT.md contains the under-three-minute English narration.

Honest limitations

• GPT output is an engineering artifact for review, never a direct robot command.
• Sample metrics are precomputed and do not change when live GPT mode is enabled.
• The public demo validates schemas, tasks, eval contracts, and kinematic case evidence only.
• Dynamics, actuator/thermal, contact-force, collision in a full simulator, and hardware execution remain downstream gates.
• Generic feedback falls back to the closest demonstration case; production deployment should connect verified project-specific metric plugins.

Security and privacy

• API keys remain server-side and .env* is ignored except .env.example.
• Unknown schema fields are rejected.
• Model text is inserted into the UI with text nodes, not HTML.
• Upstream API errors are replaced with a safe public message.
• Do not send proprietary robot data to live mode without authorization.

Supported platforms

• Linux
• macOS
• Windows with Python 3.11+ or Docker

License and third parties

ChoreoForge source code is MIT licensed. See THIRD_PARTY_NOTICES.md for dependency, case-study, trademark, and media boundaries. The checked-in MP4 previews contain video only; audio tracks were removed.