Add comprehensive README

README.md

@@ -0,0 +1,174 @@
+---
+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)