Meshy

Build a local single-user web app called "meshlab" that generates 3D meshes from a prompt or an image on my own GPU.

Stack, no substitutions:
- Python 3.11, FastAPI backend, plain HTML + vanilla JS frontend served by FastAPI
- SQLite via sqlite3 for the job table, no ORM
- three.js loaded from a CDN for the model viewer
- A single background worker thread with an in-process job queue. No Celery, no Redis.

Generation pipeline:
- Image to 3D is the primary path. Use an open-weights image-to-3D model from Hugging Face (Hunyuan3D-2 or TRELLIS, pick one and commit to it in the code and README). Load it lazily on first job and keep it resident.
- Text to 3D is a two stage path: call a local Stable Diffusion checkpoint via diffusers to make a single reference image, then feed that image into the same 3D pipeline. If no SD checkpoint is present, disable the text path in the UI with a clear message instead of failing.
- Export GLB. Also write the raw OBJ if the pipeline produces one.

UI, one page:
- Left: a text prompt box, an image upload dropzone, a "generate" button, and a seed field.
- Right: a job list with status (queued, running, done, failed), newest first, polling every 2 seconds.
- Clicking a done job loads its GLB into a three.js canvas with orbit controls, a grid floor, and one directional plus one ambient light. Add a wireframe toggle and a "download GLB" link.
- Show generation time and peak VRAM per job.

In scope: local file storage under ./outputs/{job_id}/, a jobs table, graceful failure with the traceback saved to the job row, a .env for MODEL_ID and SD_MODEL_PATH, a README that states the VRAM requirement bluntly.

Out of scope, do not build: user accounts, cloud storage, telemetry, retopology, UV unwrapping, PBR texture baking, rigging, animation, multi-GPU, payment, sharing links.

The README must include a short "limitations" section stating that output is dense triangle soup with baked vertex colors or a single texture, that it needs cleanup in Blender before engine use, and that model weight licenses must be checked before any commercial use.

# AGENTS.md — Build guide for Meshy

## Project scope
A local web app that takes a prompt or a reference image, runs an open-weights image-to-3D model on your own GPU, and hands back a viewable, downloadable GLB.

Catalogue verdict: no. The UI here is a thin shell over the actual product: generative 3D models trained on large mesh corpora, plus the GPU fleet that runs them in under a minute. You can absolutely wire up a local pipeline with open weights like Hunyuan3D or TRELLIS, and for hobby props it will get you surprisingly far. What you will not reproduce in a session is the topology cleanliness, the PBR texture quality, the remesh/retopology passes, or the auto-rigging that makes output usable without a cleanup artist. Also, one decent generation on your own hardware needs 16 to 24GB of VRAM and patience, which is exactly the cost the subscription is hiding from you. Build the local version if you enjoy the process, not because it is cheaper.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- An NVIDIA GPU with 16GB+ VRAM, ideally 24GB
- CUDA toolkit and a working PyTorch install
- Tens of GB of disk for model weights
- Tolerance for dependency hell in the 3D generation ecosystem
- Optional: an image model or API key if you want text-to-image as the first stage

## Stack and architecture
- Python 3.11, FastAPI backend, plain HTML + vanilla JS frontend served by FastAPI.
- Model original assets, edit operations, previews, and exported versions; store source IDs and timestamps for each.
- Interface for this text/image to 3D model generation workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Text to 3D is a two stage path: call a local Stable Diffusion checkpoint via diffusers to make a single reference image, then feed that image into the same 3D pipeline. If no SD checkpoint is present, disable the text path in the UI with a clear message instead of failing.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: Clean quad topology and low-poly remeshing; open pipelines give you dense, messy triangles.

## Agent implementation rules
- Project rule, data: Model original assets, edit operations, previews, and exported versions; store source IDs and timestamps for each.
- Project rule, behavior: Text to 3D is a two stage path: call a local Stable Diffusion checkpoint via diffusers to make a single reference image, then feed that image into the same 3D pipeline. If no SD checkpoint is present, disable the text path in the UI with a clear message instead of failing.
- Project rule, recovery: Text to 3D is a two stage path: call a local Stable Diffusion checkpoint via diffusers to make a single reference image, then feed that image into the same 3D pipeline. If no SD checkpoint is present, disable the text path in the UI with a clear message instead of failing.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this text/image to 3D model generation operation with sample or user-owned data: Text to 3D is a two stage path: call a local Stable Diffusion checkpoint via diffusers to make a single reference image, then feed that image into the same 3D pipeline. If no SD checkpoint is present, disable the text path in the UI with a clear message instead of failing.
- Show a concrete result or export: Export GLB. Also write the raw OBJ if the pipeline produces one.
- State the practical limit: Clean quad topology and low-poly remeshing; open pipelines give you dense, messy triangles.

## Engineering roadmap
1. Phase 1, architecture and data: Python 3.11, FastAPI backend, plain HTML + vanilla JS frontend served by FastAPI. Model original assets, edit operations, previews, and exported versions; store source IDs and timestamps for each.
2. Phase 2, implement: Text to 3D is a two stage path: call a local Stable Diffusion checkpoint via diffusers to make a single reference image, then feed that image into the same 3D pipeline. If no SD checkpoint is present, disable the text path in the UI with a clear message instead of failing.
3. Phase 3, implement: Export GLB. Also write the raw OBJ if the pipeline produces one.
4. Phase 4, review and output: Left: a text prompt box, an image upload dropzone, a "generate" button, and a seed field. Export GLB. Also write the raw OBJ if the pipeline produces one.
5. Phase 5, recovery and acceptance: Text to 3D is a two stage path: call a local Stable Diffusion checkpoint via diffusers to make a single reference image, then feed that image into the same 3D pipeline. If no SD checkpoint is present, disable the text path in the UI with a clear message instead of failing. Verify this invariant with a saved fixture: An invalid input or interrupted operation must retain the source and show a recoverable state; exported records must reload with the same IDs. State the practical limit: Clean quad topology and low-poly remeshing; open pipelines give you dense, messy triangles.

## Paid-product capabilities outside this build
- Clean quad topology and low-poly remeshing; open pipelines give you dense, messy triangles
- PBR material maps and texture upscaling that hold up under a real light rig
- Auto-rigging and animation of humanoid output
- Sub-minute generation, plus the ability to fire off ten variations without your machine seizing up
- Any commercial-use clarity around the model weights you are running

## Implementation prompt
Build a local single-user web app called "meshlab" that generates 3D meshes from a prompt or an image on my own GPU.

Stack, no substitutions:
- Python 3.11, FastAPI backend, plain HTML + vanilla JS frontend served by FastAPI
- SQLite via sqlite3 for the job table, no ORM
- three.js loaded from a CDN for the model viewer
- A single background worker thread with an in-process job queue. No Celery, no Redis.

Generation pipeline:
- Image to 3D is the primary path. Use an open-weights image-to-3D model from Hugging Face (Hunyuan3D-2 or TRELLIS, pick one and commit to it in the code and README). Load it lazily on first job and keep it resident.
- Text to 3D is a two stage path: call a local Stable Diffusion checkpoint via diffusers to make a single reference image, then feed that image into the same 3D pipeline. If no SD checkpoint is present, disable the text path in the UI with a clear message instead of failing.
- Export GLB. Also write the raw OBJ if the pipeline produces one.

UI, one page:
- Left: a text prompt box, an image upload dropzone, a "generate" button, and a seed field.
- Right: a job list with status (queued, running, done, failed), newest first, polling every 2 seconds.
- Clicking a done job loads its GLB into a three.js canvas with orbit controls, a grid floor, and one directional plus one ambient light. Add a wireframe toggle and a "download GLB" link.
- Show generation time and peak VRAM per job.

In scope: local file storage under ./outputs/{job_id}/, a jobs table, graceful failure with the traceback saved to the job row, a .env for MODEL_ID and SD_MODEL_PATH, a README that states the VRAM requirement bluntly.

Out of scope, do not build: user accounts, cloud storage, telemetry, retopology, UV unwrapping, PBR texture baking, rigging, animation, multi-GPU, payment, sharing links.

The README must include a short "limitations" section stating that output is dense triangle soup with baked vertex colors or a single texture, that it needs cleanup in Blender before engine use, and that model weight licenses must be checked before any commercial use.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.