README.md

---
title: LegoGPT-Demo
emoji: 🧱
short_description: Generate stable LEGO structures from text prompts.
app_file: app.py
sdk: gradio
sdk_version: 5.29.0
python_version: 3.11
models:
  - AvaLovelace/LegoGPT
---

# LegoGPT Demo

Gradio demo for LegoGPT.

## Prerequisites

- **Llama-3.2-1B-Instruct:** LegoGPT is fine-tuned from meta-llama/Llama-3.2-1B-Instruct, a gated model. Request access
  to the model [here](https://huggingface.co/meta-llama/Llama-3.2-1B-Instruct), then generate
  a [Hugging Face user access token](https://huggingface.co/docs/hub/en/security-tokens).
    - *If running locally,* set your access token as an environment variable: `export HF_TOKEN=<your_token>`
    - *If running on Hugging Face Spaces,* set your access token as the `HF_TOKEN` secret in the Settings tab of your
      Space.

  The model will be
  automatically downloaded upon running the code.
- **Gurobi:** Running stability analysis requires a [Gurobi licence](https://www.gurobi.com/downloads/) to use Gurobi.
  Academics may request a free licence from the Gurobi
  website [here](https://www.gurobi.com/academia/academic-program-and-licenses/).
    - *If running locally,* place the Gurobi licence file in your *home directory* or
      another [recommended location](https://support.gurobi.com/hc/en-us/articles/360013417211-Where-do-I-place-the-Gurobi-license-file-gurobi-lic).
    - *If running on Hugging Face Spaces,* the licence type must be **Web License Service (WLS)**. Set the
      `WLSACCESSID`, `WLSSECRET`, and `LICENSEID` secrets in the Settings tab of your Space to their values in your
      Gurobi licence file.
- **ImportLDraw:** Rendering LEGO visualizations requires ImportLDraw, provided as a Git submodule.
    - *If running locally,* follow these instructions to install ImportLDraw:
        - Download [Git LFS](https://git-lfs.com), then run `git lfs install`.
        - Install Git submodules with `git submodule update --init`.
        - Download the [LDraw parts library](https://library.ldraw.org/library/updates/complete.zip) and
          extract it in your *home directory*:
          `(cd ~ && wget https://library.ldraw.org/library/updates/complete.zip && unzip complete.zip)`.
            - If you wish to put the LDraw parts library in a different directory, set the environment variable
              `LDRAW_LIBRARY_PATH` to the path of the `ldraw` directory: `export LDRAW_LIBRARY_PATH=path/to/ldraw`.
    - *If running on Hugging Face Spaces,* ImportLDraw and the LDraw parts library will automatically be downloaded and
      installed by the `app.py` script.

## Running locally

Install the Python project manager [uv](https://docs.astral.sh/uv). Then run the demo with:

```zsh
uv run app.py
```

## Running on Hugging Face Spaces

Make sure the origin of this repo is set to your Space:

```zsh
git remote set-url origin git@hf.co:spaces/<your_username>/<your_space_name>
```

Then commit and push your changes to your Space with

```
git add -A && git commit -m "Update" && git push
```

> [!NOTE]
> If you've changed the dependencies in `pyproject.toml`, update the `requirements.txt` file accordingly:
> ```zsh
> uv export --format requirements-txt --no-hashes > requirements.txt
> ```
> Then, `git commit` and `git push` the changes to your Space. You may have to restart the Space for the changes to take
> effect.