README.md

---
language:
- en
license: apache-2.0
tags:
- architecture
- floor-plan
- design
- residential
- text-generation
- sft
- lora
datasets:
- Nithins03/us-architectural-floorplan-sft
base_model: Qwen/Qwen2.5-3B-Instruct
pipeline_tag: text-generation
---

# 🏠 US Architectural Floor Plan LLM

An LLM fine-tuned to design residential floor plans following **US architectural conventions** — IRC building codes, American room types, and standard design patterns.

## Model Description

- **Base Model:** [Qwen/Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct) (3B parameters)
- **Training Method:** SFT (Supervised Fine-Tuning) with LoRA adapters
- **Dataset:** [Nithins03/us-architectural-floorplan-sft](https://huggingface.co/datasets/Nithins03/us-architectural-floorplan-sft) — 12,000 examples
- **Output Format:** Design reasoning + structured JSON floor plans

## Capabilities

✅ Generate complete US residential floor plans (ranch, colonial, craftsman, farmhouse, etc.)  
✅ Follow IRC (International Residential Code) minimum standards  
✅ Include room dimensions, furniture placement, and adjacency relationships  
✅ Handle various house styles: ranch, colonial, cape cod, craftsman, modern farmhouse, split-level, cottage, Mediterranean  
✅ Provide architectural design reasoning before layouts  
✅ Output structured JSON with room polygons, openings (doors/windows), and furniture  

## Quick Start

```python
from transformers import pipeline

pipe = pipeline("text-generation", model="Nithins03/us-architectural-floorplan-llm")

messages = [
    {"role": "system", "content": "You are an expert US residential architect specializing in floor plan design. You follow IRC standards and American architectural conventions."},
    {"role": "user", "content": "Design a 2,200 sq ft craftsman home with 3 bedrooms, 2.5 bathrooms, open kitchen/living, attached garage, and mudroom."}
]

response = pipe(messages, max_new_tokens=4096)
print(response[0]["generated_text"][-1]["content"])
```

## Example Output

**Prompt:** *"Design a 1,800 sq ft ranch home with 3 bedrooms, 2 bathrooms, open floor plan, and attached 2-car garage."*

**Response:**
```
## Design Reasoning
This single-story ranch home features 3 bedrooms and 2 bathrooms across 1,800 square feet. 
The kitchen, living room, and dining area flow together in an open concept layout, characteristic 
of modern American residential design. An attached garage provides direct indoor access through 
a mudroom. The master suite is positioned for privacy with a split-bedroom layout.

## Floor Plan
{
  "style": "ranch",
  "total_area_sqft": 1812.5,
  "stories": 1,
  "rooms": [
    {"room_type": "living_room", "area_sqft": 280, "dimensions": {"width_ft": 20, "height_ft": 14}},
    {"room_type": "kitchen", "area_sqft": 180, "dimensions": {"width_ft": 15, "height_ft": 12}},
    {"room_type": "master_bedroom", "area_sqft": 225, "dimensions": {"width_ft": 15, "height_ft": 15}},
    ...
  ],
  "adjacency": [["living_room_1", "kitchen_2"], ["kitchen_2", "dining_room_3"], ...],
  "units": "feet"
}
```

## Training Details

| Parameter | Value |
|-----------|-------|
| Base Model | Qwen/Qwen2.5-3B-Instruct |
| LoRA Rank | 128 |
| LoRA Alpha | 32 |
| LoRA Target | all-linear |
| Learning Rate | 1e-4 |
| Epochs | 5 |
| Effective Batch Size | 8 |
| Max Sequence Length | 4,096 |
| Scheduler | Cosine with warmup |
| Loss | SFT (assistant-only) |

### Dataset Composition
- **2,000** room layouts from [FloorplanQA-Layouts](https://huggingface.co/datasets/OldDelorean/FloorplanQA-Layouts) (converted to US feet)
- **8,000** synthetic whole-house US floor plans (8 architectural styles)
- **2,000** architectural design Q&A knowledge examples

### Training Recipe Based On
- [OptiScene](https://arxiv.org/abs/2506.07570) — SFT + semantic reasoning before coordinates
- [DStruct2Design](https://arxiv.org/abs/2407.15723) — JSON floor plan representation  
- [LoRA Without Regret](https://huggingface.co/docs/trl/lora_without_regret) — LoRA best practices
- [Architext](https://arxiv.org/abs/2303.07519) — LLM-based floor plan generation pioneer

## How to Train

### Option 1: HuggingFace Jobs (recommended)
```bash
pip install huggingface_hub
huggingface-cli login

# Launch training
hf jobs run train.py \
    --flavor a10g-large \
    --timeout 6h \
    --secrets HF_TOKEN
```

### Option 2: Local Training
```bash
pip install torch transformers trl peft datasets accelerate trackio bitsandbytes
python train.py
```

### Hardware Requirements
- **Minimum:** 1x NVIDIA T4 (16GB VRAM) — will be slow
- **Recommended:** 1x NVIDIA A10G (24GB VRAM) — ~4 hours
- **Optimal:** 1x NVIDIA A100 (80GB VRAM) — ~2 hours

## US Architectural Styles Covered

| Style | Typical Sq Ft | Stories | Key Features |
|-------|--------------|---------|--------------|
| Ranch | 1,200–2,200 | 1 | Open floor plan, attached garage |
| Colonial | 2,000–3,500 | 2 | Center hall, formal dining, symmetrical |
| Cape Cod | 1,400–2,400 | 1.5 | Dormers, steep roof, compact |
| Craftsman | 1,500–2,800 | 1 | Covered porch, built-ins, columns |
| Modern Farmhouse | 1,800–3,200 | 2 | Large porch, open concept, mudroom |
| Split-Level | 1,500–2,500 | 3 | Tri-level, sunken living room |
| Cottage | 800–1,600 | 1 | Compact, cozy proportions |
| Mediterranean | 2,200–4,000 | 2 | Courtyard, arched doorways |

## Limitations

- Floor plans are simplified rectangular room layouts (no complex curved or irregular shapes)
- Coordinates are from a simple grid-based placement — not architecturally optimal
- No structural engineering validation (load-bearing walls, foundation, etc.)
- No MEP (Mechanical, Electrical, Plumbing) routing
- Best used as a starting point for professional architectural review

## Citation

```bibtex
@misc{us-floorplan-llm-2025,
    title={US Architectural Floor Plan LLM},
    author={Nithins03},
    year={2025},
    publisher={HuggingFace},
    url={https://huggingface.co/Nithins03/us-architectural-floorplan-llm}
}
```

## Acknowledgments

Built upon research from:
- [OptiScene](https://arxiv.org/abs/2506.07570) (Qwen3-8B SFT+DPO for layouts)
- [DStruct2Design](https://arxiv.org/abs/2407.15723) (LLaMA3 for JSON floor plans)  
- [Architext](https://arxiv.org/abs/2303.07519) (GPT-J for floor plan generation)
- [FloorplanVLM](https://arxiv.org/abs/2602.06507) (Progressive SFT for floorplans)
- [FMLM](https://arxiv.org/abs/2604.04859) (Floorplan Markup Language)