Update README with full schema documentation

README.md

@@ -1,90 +1,192 @@
-# Parametric Floorplan Generator
+# Parametric Floorplan Generator for Indian Residential Construction
 
-A model that generates 2D construction/home floor plans from parametric input (room count, total area, room types, adjacency constraints).
+A fine-tuned LLM that generates 2D construction floor plans from parametric input matching a `ProjectCreate` schema — including plot dimensions, setbacks, road side, number of bedrooms/toilets, optional rooms (pooja, study, balcony, parking, basement, stilt), and Vastu preferences.
 
-## Approach
+## What It Does
 
-This model is based on the **DStruct2Design** paper ([arXiv:2407.15723](https://arxiv.org/abs/2407.15723)):
-> *DStruct2Design: Data and Benchmarks for Data Structure Driven Generative Floor Plan Design*
+Given parameters like:
+```
+Plot: 15m x 12m rectangular
+Setbacks: front=1.5m, rear=1.0m, left=1.0m, right=1.0m
+Road side: North
+Bedrooms: 3, Toilets: 3
+Parking required, Pooja room, Balcony
+2 floors (G+1)
+City: Delhi
+```
+
+The model outputs a complete JSON floorplan with:
+- **Plot boundary** polygon (supports rectangular, L-shaped, trapezoid)
+- **Buildable boundary** (plot minus setbacks)
+- **Rooms** as polygons with dimensions, area, and center position
+- **Doors** (main entrance + internal doors between adjacent rooms)
+- **Windows** on external walls
+- **Area summaries** by floor (GF, FF, SF, stilt, basement)
+
+## Model
 
-The approach fine-tunes **Qwen2.5-1.5B-Instruct** with LoRA on the [ludolara/DStruct2Design](https://huggingface.co/datasets/ludolara/DStruct2Design) dataset, learning to output structured JSON floorplans from natural-language parametric constraints.
+| Component | Value |
+|-----------|-------|
+| Base Model | `Qwen/Qwen2.5-1.5B-Instruct` |
+| Fine-tuning | LoRA (r=16, alpha=32, dropout=0.05) |
+| Target Modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
+| Epochs | 5 |
+| Batch Size | 4 (accumulation=4) |
+| Learning Rate | 1e-4 |
+| Max Sequence Length | 4096 |
+| Precision | bf16 |
 
 ## Dataset
 
-- **Source**: `ludolara/DStruct2Design`
-- **Train**: 10,000 examples
-- **Validation**: 1,000 examples
-- **Test**: 1,000 examples
-- **Format**: Each example contains:
-  - `room_count`: number of rooms
-  - `total_area`: total floor area in m²
-  - `room_types`: list of room type strings
-  - `rooms`: list of rooms with polygon vertices, area, width, height
-  - `edges`: adjacency graph (room index pairs)
+The dataset is **synthetically generated** to match your `ProjectCreate` schema.
+
+### Input Schema (ProjectCreate)
+
+```json
+{
+  "name": "MyHouse",
+  "plot_length": 15.0,
+  "plot_width": 12.0,
+  "setback_front": 1.5,
+  "setback_rear": 1.0,
+  "setback_left": 1.0,
+  "setback_right": 1.0,
+  "road_side": "N",
+  "north_direction": "N",
+  "num_bedrooms": 3,
+  "toilets": 3,
+  "parking": true,
+  "city": "Delhi",
+  "vastu_enabled": false,
+  "road_width_m": 9.0,
+  "has_pooja": true,
+  "has_study": false,
+  "has_balcony": true,
+  "plot_shape": "rectangular",
+  "num_floors": 2,
+  "has_stilt": false,
+  "has_basement": false,
+  "municipality": "MCD",
+  "custom_room_config": null
+}
+```
+
+### Output Schema
+
+```json
+{
+  "project_name": "MyHouse",
+  "plot": {
+    "shape": "rectangular",
+    "outer_boundary": [[0,0],[15,0],[15,12],[0,12]],
+    "setbacks": {"front":1.5,"rear":1.0,"left":1.0,"right":1.0},
+    "buildable_boundary": [[1.5,1.5],[13.5,1.5],[13.5,11],[1.5,11]],
+    "road_side": "N",
+    "north_direction": "N",
+    "plot_length": 15.0,
+    "plot_width": 12.0
+  },
+  "rooms": [
+    {
+      "id": "living_1",
+      "type": "living",
+      "name": "Living Room",
+      "floor": "gf",
+      "polygon": [[1.5,1.5],[8.5,1.5],[8.5,5.5],[1.5,5.5]],
+      "area_sqm": 24.0,
+      "dimensions": {"width":7.0,"depth":4.0},
+      "position": {"x":5.0,"y":3.5}
+    },
+    ...
+  ],
+  "doors": [
+    {"id":"door_main","type":"main_entrance","width":0.9,"from":"outside","to":"living_1","position":[7.5,11.0],"orientation":"horizontal"},
+    ...
+  ],
+  "windows": [
+    {"id":"win_living_1","room":"living_1","width":1.2,"height":1.5,"position":[8.5,3.5],"orientation":"vertical"},
+    ...
+  ],
+  "dimensions": {
+    "total_built_up_area_sqm": 145.2,
+    "total_carpet_area_sqm": 128.0,
+    "ground_floor_area_sqm": 128.0,
+    "first_floor_area_sqm": 0.0,
+    "second_floor_area_sqm": 0.0,
+    "stilt_area_sqm": 0.0,
+    "basement_area_sqm": 0.0
+  },
+  "meta": {
+    "num_floors": 2,
+    "has_stilt": false,
+    "has_basement": false,
+    "vastu_enabled": false,
+    "city": "Delhi",
+    "municipality": "MCD"
+  }
+}
+```
+
+## Repository Structure
+
+| File | Purpose |
+|------|---------|
+| `train.py` | Fine-tuning script using TRL SFTTrainer + LoRA |
+| `generate.py` | Inference script — pass parametric input, get JSON floorplan |
+| `generate_synthetic_dataset.py` | Generates the training dataset from the ProjectCreate schema |
+| `README.md` | This file |
+
+## Quick Start
 
-## Usage
+### 1. Generate Dataset
 
-### Training
+```bash
+pip install datasets
+python generate_synthetic_dataset.py
+```
+
+This creates `floorplan_synthetic_dataset/` with 5,000 train, 500 val, 500 test examples.
+
+### 2. Train
 
 ```bash
 pip install transformers trl torch datasets peft accelerate trackio
+export HF_TRAINER_HUB_MODEL_ID="Karthik8nitt/parametric-floorplan-generator"
 python train.py
 ```
 
-### Inference
+Requires ~16GB VRAM (T4, RTX 3090, A10G). Runtime: 2-4 hours.
+
+### 3. Generate Floorplan
 
 ```bash
-python generate.py --room_count 4 --total_area 100 --room_types Bedroom Bathroom Kitchen LivingRoom
+python generate.py \
+  --plot_length 15 --plot_width 12 \
+  --setback_front 1.5 --setback_rear 1.0 \
+  --setback_left 1.0 --setback_right 1.0 \
+  --road_side N --num_bedrooms 3 --toilets 3 \
+  --parking --has_pooja --has_balcony \
+  --num_floors 2 --city Delhi
 ```
 
-## Example Output
+## Advanced: Custom Rooms
 
-For input:
-```
-Generate a floor plan with 4 rooms and a total area of 100 square meters.
-The room types are: Bedroom, Bathroom, Kitchen, LivingRoom.
-```
+Use `custom_room_config` to add non-standard rooms:
 
-The model outputs JSON like:
 ```json
-{
-  "rooms": [
-    {
-      "room_type": "Bedroom",
-      "area": 25.2,
-      "width": 6.1,
-      "height": 4.1,
-      "floor_polygon": [
-        {"x": 6.1, "z": 4.1},
-        {"x": 6.1, "z": 10.2},
-        {"x": 10.2, "z": 10.2},
-        {"x": 10.2, "z": 4.1}
-      ],
-      "is_regular": 1
-    },
-    ...
-  ],
-  "edges": [[0,1], [0,2], [0,3], [1,3], [2,3]],
-  "room_count": 4,
-  "total_area": 100.0,
-  "room_types": ["Bedroom", "Bathroom", "Kitchen", "LivingRoom"]
-}
+[
+  {"type": "gym", "name": "Home Gym", "min_area_sqm": 15, "floor_preference": "ff", "mandatory": true},
+  {"type": "home_theater", "name": "Theater", "min_area_sqm": 20, "floor_preference": "basement", "mandatory": true}
+]
 ```
 
-## Architecture
+## Supported Plot Shapes
 
-| Component | Value |
-|-----------|-------|
-| Base Model | Qwen2.5-1.5B-Instruct |
-| Fine-tuning | LoRA (r=16, alpha=32) |
-| Target Modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
-| Epochs | 5 |
-| Batch Size | 4 (accumulation=4) |
-| Learning Rate | 1e-4 |
-| Max Sequence Length | 2048 |
-| Precision | bf16 |
+- `rectangular`
+- `l_shaped` (with `cutout_corner`, `cutout_width`, `cutout_height`)
+- `trapezoid` (with `plot_front_width`, `plot_rear_width`, `plot_side_offset`)
 
-## Links
+## References
 
-- Paper: [DStruct2Design (arXiv:2407.15723)](https://arxiv.org/abs/2407.15723)
-- Dataset: [ludolara/DStruct2Design](https://huggingface.co/datasets/ludolara/DStruct2Design)
+- DStruct2Design paper: [arXiv:2407.15723](https://arxiv.org/abs/2407.15723)
+- Base model: [Qwen/Qwen2.5-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct)