Project Info
Inspiration
Three of us grew up building with LEGO before we ever wrote a line of code, and it turns out stud-based bricks are a surprisingly good metaphor for how robotics simulation should work: small, validated, snap-together units that compose into something physically real. The problem is that building a multi-robot sim scene today (a warehouse, a search-and-rescue maze, a swarm-coordination test) usually means hand-placing geometry or trusting a generative model to hallucinate a "plausible" environment — with no guarantee the result is collision-free, connected, or even physically assemblable.
What it does
StudForge turns a plain-English prompt (both voice and text) — "a 4-robot search-and-rescue maze with two narrow corridors, victims, debris, and a recharge pad" — into a fully validated, exportable multi-robot training environment, end to end. The system compiles a user prompt into a typed SceneSpec using Claude with schema-constrained generation, optionally accepting voice prompts through Deepgram’s nova-3 live transcription. It renders an advisory visual prior with Midjourney via its MCP server so designers can preview the scene before committing geometry, but the image only softly nudges wall placement and can never bypass validation. From there, the platform assembles and compresses the scene into stud-based brick geometry using deterministic and learned compression planners, including a Qwen model path, while gating every proposal through the same validator suite as the deterministic baseline. It validates connectivity, collision-freedom, and coverage, repairing and rechecking until the scene is sound rather than merely plausible. The system then exports a canonical USD representation, with SDF, URDF, and MJCF as downstream exports, and runs a lightweight swarm simulation with a real multi-robot team plan. During each episode, three observer agents for coverage, coordination, and collision write findings to a Redis-backed agent-memory service, then recall only bounded, validator-gated bias into the next generation, letting the system improve its training environments over time without allowing memory agents to write geometry directly. Finally, it reports the full lineage of every decision, including compiler output, compression report, validation report, and swarm metrics, as both JSON and an HTML report.
How we built it
The core is a Python backend built around Pydantic v2 contracts that define the exact I/O of every pipeline stage. For the agent layer, we used Claude to generate per-robot configs and a runnable scripted policy from the compiled EpisodeManifest, with a learned-policy slot wired in. The three observer agents persist their findings through a shared memory store with strict Redis Cloud selection. For compression, we trained and benchmarked deterministic strategies (unit, strips, greedy, exact) as a validator-gated floor, and wired a learned/hybrid path that runs inference against a Qwen 2.5 model.
Challenges we ran into
Letting Claude/Midjourney/Deepgram advise without letting them author. The hardest design constraint was making three different generative integrations strictly advisory. We initially hoped to create scene reconstructions out of Midjourney generations but quickly realized the model was too probabilistic to paint reliably consistent scene graphs. It would have been much faster to let the visual prior or the compiler "just place the bricks," but that breaks the validation guarantee the whole project is built on — we spent real time engineering the boundary so creativity stays upstream of correctness. Voice latency vs. correctness. Wiring the Deepgram WebSocket relay so transcripts land cleanly in the same compiler path as typed prompts — including recording input modality and STT model in provenance — took more debugging than expected, especially keeping the typed-text fallback fully intact when no API key is set. Trainium Pivot Our original idea used a fine-tuned compression model to convert high-fidelity USD assets into more functional blocks, yet around 9pm the trainium instance we had been working with shut down, forcing us to completely restart and train a Qwen2.5-1.5B model on a smaller EC2 instance with LoRA.
Accomplishments we're proud of
We're proud that the entire pipeline runs cleanly and produces a schema-valid scene, a zero-coverage-error compression report, a connected single-component layout, and a full observer report from all three agents. Layered on top of that honest baseline, we got Claude-driven compilation, Midjourney visual priors, Deepgram live voice input, and Redis-backed agent memory all genuinely wired into the same validated path. Getting four sponsor integrations to coexist behind one settings module, with health reporting on all nine, is the part we're most proud of engineering-wise.
What we learned
We learned that validation is gold in compiler structure. Every time we added a new model in the loop — Claude, Midjourney, Deepgram, the Qwen-based compression path — the temptation was to let it shortcut the validator. Building the advisory boundary first, and writing tests that assert validators run regardless of which backend produced the input, is what let us add four different model integrations without the system's core guarantee ever weakening. We also learned that strict failure modes (Redis, in particular) are a feature for systems that claim to demonstrate agent memory, not a bug to be smoothed over.
What's next
Finish the scene playback endpoint so the frontend can animate generated robot trajectories live instead of falling back to a static view. Train the learned robot-agent policy now that the compressed scene landscape gives us a real distribution to train against. We can now scale beyond search-and-rescue, exploring warehouse workers, assembly lines, and more. Move from JSON USD stand-ins to real OpenUSD export, and connect the swarm sim to higher-fidelity backends (Isaac, MuJoCo, BenchMARL) for sim-to-real staging.
StudForge
Text-to-brick modular multi-agent swarm-robotics training platform (hackathon slice).
Describe a swarm course in plain language and StudForge compiles it into a typed
SceneSpec, advisory visual prior, compressed assembly, validation report, export
artifacts, lightweight swarm run, and VGSY report. The project is a compiler-style
stack, not an end-to-end text-to-3D generator: every stage exchanges typed contracts
from src/studforge/contracts.py.
NL prompt → Compiler (Claude) → SceneSpec
→ Visual Prior (advisory) → Assembly → Compression
→ Canonical USD scene → Validators → exports → swarm sim
→ report (VGSY + compression metrics)
See studforge-prd-v1_4-hackathon.md for the full PRD and CLAUDE.md for the
engineering conventions.
Current Status
Fully wired and tested offline:
- Python package, Makefile, Typer CLI, FastAPI surface,
.env.example, and pytest suite. - Typed contracts in
src/studforge/contracts.py; frontend mirror infrontend/src/lib/types.ts. - Mock prompt compiler plus lazy Anthropic/Claude live adapter.
- Mock visual prior, image API adapter, and Midjourney MCP adapter; all outputs remain advisory.
- Assembly planner, deterministic compression strategies, validator suite, bounded repair loop, and repair memory.
- In-process memory fallback plus strict Redis live adapter when
REDIS_URLis set. - USD JSON fallback, parity-tagged SDF/URDF/MJCF stand-ins,
EpisodeManifest, and report generation. - Lightweight scripted swarm sim plus a PettingZoo-compatible wrapper surface.
- Compression benchmark and dry-run Trainium/Neuron training path with acceptance-gated artifacts.
- FastAPI CORS middleware driven by
CORS_ALLOWED_ORIGINS. - React/Vite/Three.js frontend with fixture mode,
/v1/generateflow, 3D scene, validator/dashboard views, and health pills.
Still needs work:
- Backend Deepgram voice endpoints are not implemented yet. The frontend voice UI/client exists, but
/v1/healthzdoes not reportdeepgram, and/v1/voice/*routes are absent. GETorWS /v1/scenes/{id}/playbackis not implemented; the frontend intentionally falls back to static robot poses.- Hardware execution is a stub until Ultimate Bots event SDK/arena details are available.
- Real OpenUSD, full simulator fidelity, live Trainium fine-tuning, hosted deployment, and live third-party credentials remain optional/live-environment work.
Quick Start
make dev # create .venv and install backend dev deps
make smoke # full offline pipeline on the example prompt
make test # pytest
make lint # ruff (non-blocking in Makefile) + naming lint
make demo # generate ./out/report.html
Direct CLI examples:
studforge generate --prompt "4-robot S&R maze with two corridors, victims, debris, recharge pad." \
--embodiment diffdrive_micro_v1 --team 4 --variants 5 --use-visual-prior --out ./out
studforge healthz # which integrations are live vs mocked
studforge compress-bench --seed 0 # compression harness -> out/compression_metrics.{csv,json}
studforge world-model --variants 5 # world-model harness -> out/world_model_harness.{csv,json}
studforge train-compression --dry-run # Trainium/Neuron dry-run training path
python -m uvicorn studforge.api:app --reload # REST surface (§19.1), GET /v1/healthz
API Surface
Implemented:
GET /v1/healthzPOST /v1/compilePOST /v1/visual-priorPOST /v1/assemblePOST /v1/compressPOST /v1/validatePOST /v1/exportPOST /v1/generateGET /v1/scenes/{scene_id}/lineage
Not implemented yet: /v1/voice/transcribe, WS /v1/voice/stream, and scene playback endpoints.
Offline-First Integrations
With an empty .env, the backend pipeline runs without network, GPU, Redis, OpenUSD,
or simulator installs. config.py currently resolves six backend/runtime integrations:
| Integration | Live trigger | Offline behavior |
|---|---|---|
| Anthropic / Claude | ANTHROPIC_API_KEY | deterministic template compiler |
| Redis | REDIS_URL | in-process lineage/cache/repair memory |
| Arize / Phoenix | OBSERVABILITY_ENABLED, PHOENIX_COLLECTOR_ENDPOINT | no-op tracer |
| Image provider | IMAGE_PROVIDER=image_api or midjourney | deterministic mock visual prior |
| Trainium / Neuron | COMPRESSION_BACKEND=learned or hybrid | deterministic compression fallback |
| Ultimate Bots | HARDWARE_ENABLED=true | in-repo lightweight sim |
.env.example also contains planned Deepgram settings, but the current backend does not
consume them yet.
Frontend
The browser UX lives in frontend/:
cd frontend
npm install
npm run dev # http://localhost:5173, /v1 proxied to localhost:8000
npm run build
The app boots from fixture JSON when the backend is unreachable. When the backend is
running, it calls /v1/generate, then best-effort compile -> visual-prior -> assemble -> validate to refresh the visible 3D scene.
North-Star Metric
VGSY: Validated Generated Scenario Yield, the fraction of generated worlds that pass validators or are auto-repaired and can run through the training/sim path without human repair.
Naming
Use StudForge / stud-based / brick-compatible / modular block in specs and exports. "LEGO" may appear only as a descriptive comparison with a non-affiliation note. This project is not affiliated with the LEGO Group.
Analysis
View
Metric
- 31
- 22
- 16
- 14
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- AnthropicIn code
- CSSIn code
- FastAPIIn code
- HTMLIn code
- Hugging FaceIn code
- JavaScriptIn code
- PythonIn code
- PyTorchIn code
- ReactIn code
- RedisIn code
- Tailwind CSSIn code
- TypeScriptIn code
12 of 12 appear in the indexed code.
AI coding agents
- Claude CodeConfig · Commits
- CodexConfig
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
963 KB
Source files
154
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
kokonut121/studforge
181 files · 11.0 MB · @ a21d04b
Structure
Interface
43 files · 24%Screens, components and styles rendered to the user.
API & routing
2 files · 1%Request entry points: routes, handlers and controllers.
Application logic
81 files · 45%Domain rules, services and shared utilities.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- Python43%
- TypeScript31%
- Markdown26%
- HTML0%
- CSS0%
- JavaScript0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
pyproject.toml
pypi · 37- fastapi
- networkx
- numpy
- pandas
- pillow
- pydantic
- pydantic-settings
- redis
- redisvl
- typer
- uvicorn
- +26 more
frontend/package.json
npm · 24- @react-three/drei
- @react-three/fiber
- @tanstack/react-query
- clsx
- framer-motion
- lucide-react
- react
- react-dom
- react-hot-toast
- recharts
- tailwind-merge
- three
- zustand
- +11 more
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Feature verification
Claude-based prompt compiler with schema-constrained generationVerified
Compiles a user prompt into a typed SceneSpec using Claude with schema-constrained generation
Claimed on Devposthigh confidencesrc/studforge/compiler/anthropic_compiler.py:118— client.messages.create called with a tool schema (SCENE_SPEC_TOOL/SCENE_SPEC_JSON_SCHEMA) and tool_choice forcing emit_scene_spec, with a bounded repair loopsrc/studforge/compiler/mock_compiler.py:8— Deterministic template compiler used when no ANTHROPIC_API_KEY is set
Connectivity/collision/coverage validation with repair loopVerified
Validates connectivity, collision-freedom, and coverage, repairing and rechecking until the scene is sound
Claimed on Devposthigh confidencesrc/studforge/validators/checks/__init__.py:66— collision_overlap check implementedsrc/studforge/validators/checks/__init__.py:96— spawn_goal_reachable connectivity check via BFSsrc/studforge/pipeline.py:175— _repair_loop applies planner.repair and reruns validator suite up to MAX_REPAIR_RETRIES
Deterministic + learned/Qwen compression plannersVerified
Compresses scene into stud-based brick geometry using deterministic and learned compression planners, including a Qwen model path
Claimed on Devposthigh confidencesrc/studforge/compression/strategies.py:14— unit/strips/greedy/exact deterministic strategies implementedsrc/studforge/compression/learned.py:173— Loads transformers AutoModelForCausalLM/Seq2Seq keyed off COMPRESSION_MODEL_PATH/COMPRESSION_BASE_MODELsrc/studforge/config.py:55— compression_base_model default is Qwen/Qwen2.5-1.5B-Instruct
FastAPI CORS middleware driven by CORS_ALLOWED_ORIGINSVerified
FastAPI CORS middleware is configured from CORS_ALLOWED_ORIGINS
Claimed on Devposthigh confidencesrc/studforge/api/app.py:31— app.add_middleware(CORSMiddleware, allow_origins=get_settings().cors_origins(), ...)src/studforge/config.py:77— cors_allowed_origins settings field feeding cors_origins()
FastAPI implements the full documented v1 REST/WS surfaceVerified
FastAPI implements healthz, compile, visual-prior, assemble, compress, validate, export, generate, lineage, agents/init, scene observers, and voice endpoints
Claimed on Devposthigh confidencesrc/studforge/api/app.py:384— GET /v1/healthzsrc/studforge/api/app.py:194— POST /v1/generatesrc/studforge/api/app.py:306— GET /v1/scenes/{scene_id}/lineagesrc/studforge/api/app.py:319— POST /v1/voice/transcribe
Full lineage report as JSON and HTMLVerified
Reports the full lineage of every decision, including compiler output, compression report, validation report, and swarm metrics, as both JSON and an HTML report
Claimed on Devposthigh confidencesrc/studforge/reporting/report.py:17— Writes report.json and report.html including compression, validation, visual_prior, canonical_scene, swarm metrics, observer findings
Lightweight swarm simulation with multi-robot team planVerified
Runs a lightweight swarm simulation with a real multi-robot team plan
Claimed on Devposthigh confidencesrc/studforge/sim/swarm.py:167— run_swarm implements a scripted BFS-based swarm simulationsrc/studforge/agents/team.py:29— build_team constructs AgentConfig/RobotTeamPlan from EpisodeManifestsrc/studforge/sim/pettingzoo_env.py:17— SwarmParallelEnv is a PettingZoo-compatible wrapper with lazy/optional import
Midjourney MCP advisory visual priorVerified
Renders an advisory visual prior with Midjourney via its MCP server; image only softly nudges wall placement and cannot bypass validation
Claimed on Devposthigh confidencesrc/studforge/visual_prior/midjourney_mcp.py:67— fastmcp.Client used against an official Midjourney MCP endpointsrc/studforge/visual_prior/image_providers.py:87— get_live_image_provider selects mock/image_api/midjourney backendssrc/studforge/assembly/planner.py:188— prior_bias only nudges a wall-sampling threshold, never writes geometry directly
Nine wired integration health mapVerified
Getting four sponsor integrations to coexist behind one settings module, with health reporting on all nine
Claimed on Devposthigh confidencesrc/studforge/config.py:104— health() returns anthropic, redis, arize, image_provider, trainium, ultimate_bots, robot_agents, observer_agents, deepgram: nine keys
Observer agents with Redis-backed memory and bounded validator-gated recallVerified
Three observer agents for coverage, coordination, and collision write findings to a Redis-backed agent-memory service, then recall only bounded, validator-gated bias into the next generation
Claimed on Devposthigh confidencesrc/studforge/agents/observers.py:145— CoverageObserver, CoordinationObserver (180), CollisionObserver (214) all presentsrc/studforge/memory/redis_store.py:1— RedisVL-backed store, live-fatal on connection error per strict Redis policysrc/studforge/agents/observers.py:286— recall_team_advisory clamps recalled bias to fixed ranges, producing only soft knob adjustments, never geometry
Pydantic v2 contracts as single source of truth for stage I/OVerified
Core is a Python backend built around Pydantic v2 contracts that define the exact I/O of every pipeline stage
Claimed on readmehigh confidencesrc/studforge/contracts.py:45— SceneSpec, VisualPrior (58), AssemblyGraph (71), CompressionReport (93), ValidationReport (113), EpisodeManifest (182) all subclass pydantic.BaseModel
React/Vite/Three.js frontend with fixture mode, 3D scene, dashboard, health pillsVerified
React/Vite/Three.js frontend with fixture mode, /v1/generate flow, 3D scene, validator/dashboard views, and health pills
Claimed on readmemedium confidencefrontend/package.json:14— @react-three/fiber and @react-three/drei dependencies presentfrontend/src/components/scene/Scene3D.tsx— 3D scene component existsfrontend/src/components/dashboard/HealthPills.tsx— Health pill UI component existsfrontend/src/fixtures— Fixture JSON files for offline/fixture mode
Robot-agent learned policy stub deferred to scripted fallbackVerified
Learned-policy slot wired in, with training deferred until compressed policy landscape is known
Claimed on Devposthigh confidencesrc/studforge/agents/policies.py:98— LearnedPolicy raises PolicyNotTrainedError without a real artifactsrc/studforge/agents/policies.py:148— get_policy falls back to ScriptedPolicy when learned policy is not ready
Scene playback endpoint not implementedVerified
GET or WS /v1/scenes/{id}/playback is not implemented; frontend falls back to static robot poses
Claimed on readmehigh confidencesrc/studforge/api/app.py:1— No 'playback' route exists anywhere in app.py (grep returns no matches), matching the claimed gap
Trainium/Neuron dry-run training with acceptance-gated artifactsVerified
Compression benchmark and dry-run Trainium/Neuron training path with acceptance-gated artifacts
Claimed on readmehigh confidencesrc/studforge/compression/training.py:58— dry_run parameter threading through training pathsrc/studforge/compression/training.py:790— optimum.neuron.NeuronTrainer/NeuronTrainingArguments lazily importedsrc/studforge/compression/training.py:165— _acceptance_report gates promotion of a trained artifact
Typer CLI command surfaceVerified
CLI implements generate, validate, compress-bench, train-compression, agents-init, healthz, world-model commands
Claimed on readmehigh confidencesrc/studforge/cli.py:13— generate commandsrc/studforge/cli.py:142— train_compression commandsrc/studforge/cli.py:118— world-model commandsrc/studforge/cli.py:256— healthz command
Ultimate Bots hardware bridge stubVerified
Ultimate Bots hardware execution is a stub until event SDK/arena details are available
Claimed on readmehigh confidencesrc/studforge/hardware/ultimate_bots.py:18— Lazily imports rclpy then raises NotImplementedError pending SDK bindings at the event
Validator-gated compression proposalsVerified
Gates every compression proposal through the same validator suite as the deterministic baseline
Claimed on Devpostmedium confidencesrc/studforge/compression/__init__.py:104— _run_backend accepts learned/hybrid output only if coverage error is zero and part count is not worse than greedy baseline, else falls back to greedysrc/studforge/pipeline.py:132— Resulting graph then passes through the same validator suite uniformly regardless of compression backend
Voice prompt entry via Deepgram nova-3Verified
Optionally accepting voice prompts through Deepgram's nova-3 live transcription
Claimed on Devposthigh confidencesrc/studforge/voice/deepgram_stt.py:74— Live websocket streaming transcription implemented via lazy deepgram-sdk importsrc/studforge/config.py:64— deepgram_model default is 'nova-3'src/studforge/api/app.py:337— WS /v1/voice/stream relay endpoint present
Canonical USD export with SDF/URDF/MJCF downstream exportsCode-supported
Exports a canonical USD representation, with SDF, URDF, and MJCF as downstream exports
Claimed on Devposthigh confidencesrc/studforge/usd_export/usd_scene.py:80— Real OpenUSD (pxr) used if installed, else writes a .usd.json stand-in tagged usd_json_standinsrc/studforge/usd_export/exporters.py:76— SDF/URDF/MJCF written as .{fmt}.json parity-tagged stand-ins, not real robotics-format serializers
Real OpenUSD export (vs JSON stand-in)Code-supported
Move from JSON USD stand-ins to real OpenUSD export (listed as future work in Devpost, but description text also implies canonical USD is delivered)
Claimed on Devpostmedium confidencesrc/studforge/usd_export/usd_scene.py:80— pxr path exists but only activates if OpenUSD is installed; default/verified offline path is a JSON stand-in, consistent with 'what's next' framing
Live Isaac/MuJoCo/BenchMARL sim-to-real staging (future work)Claimed only
Connect the swarm sim to higher-fidelity backends (Isaac, MuJoCo, BenchMARL) for sim-to-real staging
Claimed on Devposthigh confidenceRobot-agent policy training on compressed landscape (future work)Blocked
Train the learned robot-agent policy now that the compressed scene landscape gives a real distribution to train against
Claimed on Devposthigh confidence
An AI agent derived these features from the project’s Devpost page and readme, then searched the code for each one. Verified features are backed by cited code; claimed-only features had no supporting code, which is not by itself proof a feature is missing.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.