debim 0.2.0__tar.gz

debim-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prida Takon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

debim-0.2.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: debim
+Version: 0.2.0
+Summary: A minimal, Git-native, declarative BIM engine (Building-as-Code) designed for AI agents and humans.
+Author: PRIDA-TAKON
+License-Expression: MIT
+Keywords: bim,building-as-code,openbim,ifc,declarative,cad,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: trimesh>=4.0.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: ifc
+Requires-Dist: ifcopenshell>=0.7.0; extra == "ifc"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="debim logo" width="740" />
+</p>
+
+<p align="center">
+  <strong>A minimal, Git-native, declarative BIM engine (Building-as-Code) designed for AI agents and humans.</strong>
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python: 3.11+" /></a>
+  <a href="https://technical.buildingsmart.org/"><img src="https://img.shields.io/badge/BIM-IFC4--Minimal-brightgreen.svg" alt="BIM: IFC4" /></a>
+  <a href="tests/"><img src="https://img.shields.io/badge/tests-131%20passed-success.svg" alt="Tests: 131 Passed" /></a>
+  <a href="https://www.kaggle.com/code/pridatakon/debim-3d-visual-balanced-benchmark"><img src="https://img.shields.io/badge/visual%20fidelity-85.5%25%20median-brightgreen.svg" alt="Visual Fidelity: 85.5% Median" /></a>
+  <a href="https://prida-takon.github.io/debim/"><img src="https://img.shields.io/badge/Live%203D%20Demo-Interactive%20Viewer-2ea44f.svg?logo=three.js" alt="Live 3D Demo" /></a>
+</p>
+
+<p align="center">
+  <a href="https://prida-takon.github.io/debim/">
+    <img src="https://img.shields.io/badge/🔴%20Click%20Here-Open%20Live%203D%20Viewer%20(No%20Install)-2ea44f?style=for-the-badge&logo=three.js" alt="Open Live 3D Demo" />
+  </a>
+</p>
+
+---
+
+<p align="center">
+  <table width="100%">
+    <tr>
+      <td width="50%" align="center" valign="top">
+        <b>💻 Modern CLI, QTO & Costing Engine</b><br>
+        <img src="docs/assets/terminal_preview.png" alt="debim Terminal CLI - Farnsworth House" width="100%" />
+      </td>
+      <td width="50%" align="center" valign="top">
+        <b>🌐 Zero-Install 3D Web Viewer (<a href="https://prida-takon.github.io/debim/">Try Live Demo</a>)</b><br>
+        <a href="https://prida-takon.github.io/debim/"><img src="docs/assets/viewer_preview.png" alt="debim 3D HTML Viewer - Farnsworth House (1951)" width="100%" /></a>
+      </td>
+    </tr>
+  </table>
+  <sub>🏛️ <i>Showcase: Ludwig Mies van der Rohe's iconic <b>Farnsworth House (1951)</b> — compiled from declarative YAML (<a href="examples/farnsworth_house/project.yaml">examples/farnsworth_house/project.yaml</a>) into standard IFC4 and rendered in real-time in a lightweight 3D web viewer.</i></sub>
+</p>
+
+> [!TIP]
+> **🤖 Authored 100% by AI Agent (Antigravity powered by Gemini 3.8 Flash):**  
+> โมเดลสถาปัตยกรรมระดับโลกชิ้นนี้ **ไม่ได้เขียนด้วยมือมนุษย์ทีละบรรทัด!** แต่เกิดจากการให้ **AI Coding Agent (Antigravity ขับเคลื่อนด้วย Gemini 3.8 Flash)** ทำการสืบค้นข้อมูลแบบแปลน มิติโครงสร้าง และระยะกริดทางประวัติศาสตร์ของ Farnsworth House ด้วยตนเอง แล้วสังเคราะห์โค้ด Declarative YAML (`project.yaml`) ออกมาโดยอัตโนมัติ ก่อนสั่งให้ `debim` ถอดปริมาณงาน (QTO) และคอมไพล์เป็น IFC4 มาตรฐานสากลในเสี้ยววินาที — ยืนยันว่า **คุณไม่จำเป็นต้องพิมพ์โค้ดเองทั้งหมดหากทำงานร่วมกับ AI Agent!**
+
+---
+
+## 🎯 Why debim? (จุดกำเนิดและปรัชญาของ debim)
+
+> *"หัวใจของ debim เริ่มจากการอยากให้ AI ทำ BOQ แต่การให้ AI คำนวณตึกทั้งหลังตรงๆ AI ตายแน่ จึงต้องใช้แบบจำลองคณิตศาสตร์ (BIM) ทว่ามาตรฐาน IFC ดั้งเดิมก็ซับซ้อนเกินไป หนักสมอง AI อีก จึงกลั่นออกมาเป็น Declarative YAML — แต่ผลพลอยได้ที่ได้รับกลับยิ่งใหญ่กว่าเป้าหมายแรกเริ่ม"*
+
+Traditional BIM tools (like Revit or Archicad) were built over 25 years ago for humans clicking with computer mice. They lock architectural data in heavy, proprietary gigabyte files (`.rvt`), charge thousands of dollars in annual licenses, and remain completely opaque to modern automation and AI agents.
+
+**debim** ยึดมั่นใน **5 เสาหลักแห่งการออกแบบ (Core Tenets)**:
+1. **Building-as-Code & Git-Native:** อาคารคือซอฟต์แวร์ แสดงออกเป็นข้อความ YAML ขนาดกะทัดรัด (Kilobytes ไม่ใช่ Gigabytes) เพื่อให้ทำ Version Control, Git diff, และ Branching ตรวจสอบการแก้ไขได้ทีละบรรทัด
+2. **Deterministic Code Compliance:** กฎหมายอาคารและข้อกำหนดวิศวกรรมถูกแปลงเป็น Unit Test (`pytest`) รันตรวจจับข้อผิดพลาดและระยะร่นใน 0.01 วินาทีก่อนลงมือก่อสร้างจริง
+3. **Zero-License & Zero-Friction Visualization:** ตรวจสอบความถูกต้องทางเรขาคณิตได้ทันทีผ่าน 3D HTML Viewer น้ำหนักเบา เปิดบนเบราว์เซอร์หรือมือถือได้ทันที ไม่ต้องมีไลเซนส์ซอฟต์แวร์ราคาแพง
+4. **Universal Bridge & Dual Representation:** ตัวกลางเชื่อมโยง 2D, 3D (SketchUp/Blender), และ IFC โดยผสมผสาน 90% Primitives สำหรับคำนวณโครงสร้างและ BOQ + 10% Baked GLB Asset สำหรับงานสถาปัตย์ประณีต
+5. **Human & AI Super-Collaboration:** ออกแบบให้มี Explicit Uncertainty (`review_status: needs_review`) ให้มนุษย์และ AI ร่วมมือกันตรวจและเติมเต็มสเปกได้อย่างไร้รอยต่อ
+
+---
+
+## 🤖 AI-Agent Installation (ติดตั้งง่ายที่สุดในโลกด้วย AI ของคุณ)
+
+If you use an AI coding assistant (like **Antigravity, Cursor, Claude Code, Jules, or ChatGPT/Copilot**), you don't even need to install it manually!
+
+Just copy and send this prompt to your AI:
+
+> *"Please read https://github.com/PRIDA-TAKON/debim and `AGENTS.md`, install debim in my environment, and run `debim --help` to verify."*
+
+Your agent will inspect the repository, install the dependencies, and verify everything automatically.
+
+---
+
+## 🚀 Manual Quickstart
+
+### 1. Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/PRIDA-TAKON/debim.git
+cd debim
+
+# Install in editable mode
+pip install -e .
+
+# Or with full dev & IFC compiler tools
+pip install -e ".[ifc,dev]"
+```
+
+### 2. Basic Commands
+
+```bash
+# Initialize a new project
+debim init my-project
+
+# Validate schema syntax & grid references
+debim validate -m examples/farnsworth_house/project.yaml
+
+# Run automated building code compliance checks (pytest)
+debim test
+
+# Calculate Quantitative Take-Off (Steel weight, stone volume, glass area)
+debim qto -m examples/farnsworth_house/project.yaml
+
+# Generate project-scoped price template with international classifications
+debim cost template -m examples/farnsworth_house/project.yaml -o prices.template.yaml
+
+# Estimate project budget & export BOQ to CSV
+debim cost -m examples/farnsworth_house/project.yaml -p examples/farnsworth_house/prices.yaml -o dist/boq.csv
+
+# Scaffold a new BIM element class boilerplate
+debim scaffold element IfcRailing
+
+# Preview 3D model in your browser (Three.js with Hierarchical Layer Explorer)
+debim view -m examples/farnsworth_house/project.yaml
+
+# Compile declarative YAML to standard IFC4 building model
+debim compile -m examples/farnsworth_house/project.yaml -o dist/farnsworth_house.ifc
+```
+
+---
+
+## 🏗️ Example `project.yaml`
+
+```yaml
+schema: IFC4-Minimal
+project:
+  id: PRJ-2026-001
+  name: "Townhouse-Feasibility"
+  units: { length: METER, area: SQUARE_METER, volume: CUBIC_METER }
+
+# 1. Spatial Structure
+spatial_structure:
+  storeys:
+    - id: L1
+      name: "Level 1"
+      elevation: 0.00
+      height: 3.50
+    - id: L2
+      name: "Level 2"
+      elevation: 3.50
+      height: 3.20
+
+# 2. Reference Grid Axes
+grids:
+  axes_x: { A: 0.00, B: 4.00, C: 8.00 }
+  axes_y: { 1: 0.00, 2: 5.00, 3: 10.00 }
+
+# 3. Materials
+materials:
+  - id: CONC_240
+    name: "Concrete 240 ksc"
+    category: concrete
+    unit_cost_ref: "MAT-CONC-01"
+  - id: AAC_75
+    name: "AAC Block 7.5cm"
+    category: masonry
+    unit_cost_ref: "MAT-AAC-01"
+
+# 4. Elements
+elements:
+  # Column placed at grid intersection [A, 1]
+  - class: IfcColumn
+    tag: C-A1
+    material: CONC_240
+    profile: { shape: BOX, width: 0.20, depth: 0.20 }
+    placement:
+      grid: [A, 1]
+      base_storey: L1
+      top_storey: L2
+    reinforcement:
+      main: "4-DB16"
+      stirrups: "RB6 @ 0.15m"
+
+  # Beam spanning between [A, 1] and [B, 1]
+  - class: IfcBeam
+    tag: B-A1_B1
+    material: CONC_240
+    profile: { shape: BOX, width: 0.20, depth: 0.40 }
+    placement:
+      from_grid: [A, 1]
+      to_grid: [B, 1]
+      storey: L2
+    reinforcement:
+      main_top: "2-DB16"
+      main_bottom: "3-DB20"
+      stirrups: "RB9 @ 0.15m"
+
+  # Wall with door host-child relationship
+  - class: IfcWall
+    tag: W-A1_A2
+    material: AAC_75
+    thickness: 0.075
+    height: 3.10
+    placement:
+      from_grid: [A, 1]
+      to_grid: [A, 2]
+      storey: L1
+    children:
+      - class: IfcDoor
+        tag: D1
+        dimensions: { width: 0.90, height: 2.00 }
+        offset_distance: 1.20
+```
+
+---
+
+## 🔬 Empirical Research & Benchmark (การทดสอบระดับอุตสาหกรรม)
+
+debim ให้ความสำคัญกับความถูกต้องทางวิศวกรรมและการทดสอบแบบเปิดเผย ตรวจสอบซ้ำได้จริง (100% Reproducible Open Science) บน **Kaggle Cloud Multi-Core Benchmark Suite**:
+
+### 1. ⚖️ 3D Visual Regression & Alignment Benchmark (255 อาคารจริงสากล)
+
+<p align="center">
+  <a href="https://www.kaggle.com/code/pridatakon/debim-3d-visual-balanced-benchmark">
+    <img src="https://img.shields.io/badge/Kaggle-Run%20Reproducible%20Benchmark-20BEFF?logo=kaggle&style=for-the-badge" alt="Kaggle Benchmark" />
+  </a>
+</p>
+
+การทดสอบความแม่นยำด้านเรขาคณิต 3 มิติ (3D Visual Fidelity) แบบปิดตาเทียบกับ IFC ต้นฉบับผ่าน **Geometry Variant Deduplication + Balanced Macro-Averaging** บน 4,695 ชิ้นส่วนตัวแทน:
+
+- **🎯 85.50% Median Visual Fidelity:** ทะลุเกณฑ์มาตรฐานสากล ($\ge 85\%$) ครอบคลุมเกินกึ่งหนึ่งของโมเดลทดสอบ
+- **🏗️ 89.07% Structural Match:** งานโครงสร้างรับแรงหลัก (เสา คาน ผนัง ฐานราก) มีความเสถียรระดับเกรด A+
+- **⚡ 82.64% MEP System Match:** งานระบบท่อ ระบบปรับอากาศ และอุปกรณ์ไฟฟ้าอยู่ในตำแหน่งและระนาบที่ถูกต้อง
+
+#### 📈 วิวัฒนาการเปรียบเทียบข้าม 3 เจเนอเรชัน (Progression Across Waves):
+
+| ตัวชี้วัดสากล (Global Metric) | V1 (Baseline) | V2 (Wave 1-2) | V3 (Wave 4 ล่าสุด) | $\Delta$ พัฒนาขึ้นสะสม |
+|---|:---:|:---:|:---:|:---:|
+| **🎯 Median Visual Match (ค่ามัธยฐาน)** | 80.90% | 84.90% | **85.50%** | 🏆 **+4.60% (ทะลุเป้า 85%)** |
+| **⚖️ Macro Average Visual Match** | 70.57% | 77.60% | **77.71%** | 🟢 **+7.13%** |
+| **📊 Micro Average Visual Match** | 72.24% | 80.35% | **80.46%** | 🟢 **+8.23%** |
+| **ชิ้นส่วนที่ผ่านเกณฑ์ ($\ge 85\%$)** | 2,865 ชิ้น | 3,140 ชิ้น | **3,135 ชิ้น** | 🟢 **+270 ชิ้น** |
+| **หมวดหมู่งานระบบและตกแต่งที่ก้าวกระโดด** | | | | |
+| • *ฝ้าเพดาน (`IfcCovering`)* | 11.4% | 89.0% | **89.0%** | 🟢 **+77.6% (ผ่านเกณฑ์)** |
+| • *วาล์วระบบท่อ (`IfcValve`)* | 0.0% | 82.2% | **82.4%** | 🟢 **+82.4% (พุ่งจากศูนย์)** |
+| • *แผ่นเหล็กโครงสร้าง (`IfcPlate`)* | 10.2% | 88.9% | **87.1%** | 🟢 **+76.9% (ผ่านเกณฑ์)** |
+| • *เหล็กค้ำยันเฉียง (`IfcMember`)* | 91.8% | 91.6% | **92.4%** | 🟢 **+0.8% (3D Vector Pitch)** |
+
+👉 *ต้องการตรวจสอบการทดลองเชิงลึกหรือรันซ้ำด้วยตนเอง? ดูโค้ดและดาต้าเซ็ตได้ที่ [Kaggle Benchmark Notebook](https://www.kaggle.com/code/pridatakon/debim-3d-visual-balanced-benchmark)*
+
+---
+
+### 2. 📦 Roundtrip Retention & Storage Reduction Study (407 อาคารสากล)
+
+debim ได้รับการทดสอบอย่างเข้มงวดกับโมเดลอาคารจริงกว่า **407 โครงการ** (สถาปัตยกรรม โครงสร้าง และ MEP โรงพยาบาล):
+
+- **100.0% Median Retention Rate:** โมเดลส่วนใหญ่สามารถสกัดและ Re-compile กลับสู่มาตรฐาน IFC4 ได้ครบถ้วนทุกชิ้นงาน
+- **91.6% Average Storage Reduction:** ลดขนาดไฟล์จาก IFC ดิบลงเฉลี่ย 91%
+- **558M+ LLM Tokens Saved:** ประหยัดบริบทของโมเดลภาษาไปได้มากกว่า **558,629,804 โทเคน**
+- **100.0% Modern Schema Crash-Resilience:** ไม่พบ Fatal Crash หรือ Unhandled Exception บนมาตรฐาน IFC2X3 และ IFC4
+
+📖 **อ่านรายงานวิจัยฉบับเต็ม:** [debim: An Empirical Study of Declarative Building-as-Code on 407 Heterogeneous Real-World OpenBIM Models](docs/research/2026_empirical_study_407_ifc_models.md)  
+📦 **Kaggle Public Benchmark Dataset:** [debim-5000-ifc-benchmark](https://www.kaggle.com/datasets/pridatakon/debim-5000-ifc-benchmark)  
+⚡ **Kaggle Automated Stress Test:** [debim-ifc-stress-test](https://www.kaggle.com/code/pridatakon/debim-ifc-stress-test)
+
+---
+
+## ❓ Frequently Asked Questions (FAQ)
+
+<details>
+<summary><b>Why YAML instead of JSON, Python, or Excel?</b></summary>
+<br>
+YAML is clean, concise, supports nested hierarchies, and allows comments (essential for architectural notes). Unlike JSON, it has no noisy braces. Unlike Excel, it is 100% Git-friendly, diffable, and conflict-resolvable. It serves as a pure declarative DSL (Domain-Specific Language)—just like Kubernetes, Docker Compose, and GitHub Actions.
+</details>
+
+<details>
+<summary><b>How do I place off-grid items (internal partitions, cantilever beams)?</b></summary>
+<br>
+Use relative offsets: `placement: { grid: [A, 1], offset: [1.20, 0.50] }`. Just like pulling a tape measure on site from the nearest grid line.
+</details>
+
+<details>
+<summary><b>Does this replace Revit or AutoCAD?</b></summary>
+<br>
+No, it complements them. debim handles the early-stage upstream workload: rapid feasibility, parametric sizing, AI generation, instant QTO/costing, and automated building law validation. Once validated, run <code>debim compile</code> to export standard IFC4 and load it directly into BlenderBIM, FreeCAD, or Revit for 2D drafting and detail annotations.
+</details>
+
+---
+
+## 📄 License & Attribution
+
+- **Software Code:** Licensed under the [MIT License](LICENSE) — Copyright (c) 2026 Prida Takon.
+- **Research & Technical Reports:** Licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
+- **Benchmark Datasets & Sample Models:** Test fixtures in `tests/fixtures/` originate from [buildingSMART International](https://github.com/buildingSMART) and the Open IFC Model Repository under CC BY 4.0 / CC-BY-3.0.

debim-0.2.0/README.md

@@ -0,0 +1,286 @@
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="debim logo" width="740" />
+</p>
+
+<p align="center">
+  <strong>A minimal, Git-native, declarative BIM engine (Building-as-Code) designed for AI agents and humans.</strong>
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python: 3.11+" /></a>
+  <a href="https://technical.buildingsmart.org/"><img src="https://img.shields.io/badge/BIM-IFC4--Minimal-brightgreen.svg" alt="BIM: IFC4" /></a>
+  <a href="tests/"><img src="https://img.shields.io/badge/tests-131%20passed-success.svg" alt="Tests: 131 Passed" /></a>
+  <a href="https://www.kaggle.com/code/pridatakon/debim-3d-visual-balanced-benchmark"><img src="https://img.shields.io/badge/visual%20fidelity-85.5%25%20median-brightgreen.svg" alt="Visual Fidelity: 85.5% Median" /></a>
+  <a href="https://prida-takon.github.io/debim/"><img src="https://img.shields.io/badge/Live%203D%20Demo-Interactive%20Viewer-2ea44f.svg?logo=three.js" alt="Live 3D Demo" /></a>
+</p>
+
+<p align="center">
+  <a href="https://prida-takon.github.io/debim/">
+    <img src="https://img.shields.io/badge/🔴%20Click%20Here-Open%20Live%203D%20Viewer%20(No%20Install)-2ea44f?style=for-the-badge&logo=three.js" alt="Open Live 3D Demo" />
+  </a>
+</p>
+
+---
+
+<p align="center">
+  <table width="100%">
+    <tr>
+      <td width="50%" align="center" valign="top">
+        <b>💻 Modern CLI, QTO & Costing Engine</b><br>
+        <img src="docs/assets/terminal_preview.png" alt="debim Terminal CLI - Farnsworth House" width="100%" />
+      </td>
+      <td width="50%" align="center" valign="top">
+        <b>🌐 Zero-Install 3D Web Viewer (<a href="https://prida-takon.github.io/debim/">Try Live Demo</a>)</b><br>
+        <a href="https://prida-takon.github.io/debim/"><img src="docs/assets/viewer_preview.png" alt="debim 3D HTML Viewer - Farnsworth House (1951)" width="100%" /></a>
+      </td>
+    </tr>
+  </table>
+  <sub>🏛️ <i>Showcase: Ludwig Mies van der Rohe's iconic <b>Farnsworth House (1951)</b> — compiled from declarative YAML (<a href="examples/farnsworth_house/project.yaml">examples/farnsworth_house/project.yaml</a>) into standard IFC4 and rendered in real-time in a lightweight 3D web viewer.</i></sub>
+</p>
+
+> [!TIP]
+> **🤖 Authored 100% by AI Agent (Antigravity powered by Gemini 3.8 Flash):**  
+> โมเดลสถาปัตยกรรมระดับโลกชิ้นนี้ **ไม่ได้เขียนด้วยมือมนุษย์ทีละบรรทัด!** แต่เกิดจากการให้ **AI Coding Agent (Antigravity ขับเคลื่อนด้วย Gemini 3.8 Flash)** ทำการสืบค้นข้อมูลแบบแปลน มิติโครงสร้าง และระยะกริดทางประวัติศาสตร์ของ Farnsworth House ด้วยตนเอง แล้วสังเคราะห์โค้ด Declarative YAML (`project.yaml`) ออกมาโดยอัตโนมัติ ก่อนสั่งให้ `debim` ถอดปริมาณงาน (QTO) และคอมไพล์เป็น IFC4 มาตรฐานสากลในเสี้ยววินาที — ยืนยันว่า **คุณไม่จำเป็นต้องพิมพ์โค้ดเองทั้งหมดหากทำงานร่วมกับ AI Agent!**
+
+---
+
+## 🎯 Why debim? (จุดกำเนิดและปรัชญาของ debim)
+
+> *"หัวใจของ debim เริ่มจากการอยากให้ AI ทำ BOQ แต่การให้ AI คำนวณตึกทั้งหลังตรงๆ AI ตายแน่ จึงต้องใช้แบบจำลองคณิตศาสตร์ (BIM) ทว่ามาตรฐาน IFC ดั้งเดิมก็ซับซ้อนเกินไป หนักสมอง AI อีก จึงกลั่นออกมาเป็น Declarative YAML — แต่ผลพลอยได้ที่ได้รับกลับยิ่งใหญ่กว่าเป้าหมายแรกเริ่ม"*
+
+Traditional BIM tools (like Revit or Archicad) were built over 25 years ago for humans clicking with computer mice. They lock architectural data in heavy, proprietary gigabyte files (`.rvt`), charge thousands of dollars in annual licenses, and remain completely opaque to modern automation and AI agents.
+
+**debim** ยึดมั่นใน **5 เสาหลักแห่งการออกแบบ (Core Tenets)**:
+1. **Building-as-Code & Git-Native:** อาคารคือซอฟต์แวร์ แสดงออกเป็นข้อความ YAML ขนาดกะทัดรัด (Kilobytes ไม่ใช่ Gigabytes) เพื่อให้ทำ Version Control, Git diff, และ Branching ตรวจสอบการแก้ไขได้ทีละบรรทัด
+2. **Deterministic Code Compliance:** กฎหมายอาคารและข้อกำหนดวิศวกรรมถูกแปลงเป็น Unit Test (`pytest`) รันตรวจจับข้อผิดพลาดและระยะร่นใน 0.01 วินาทีก่อนลงมือก่อสร้างจริง
+3. **Zero-License & Zero-Friction Visualization:** ตรวจสอบความถูกต้องทางเรขาคณิตได้ทันทีผ่าน 3D HTML Viewer น้ำหนักเบา เปิดบนเบราว์เซอร์หรือมือถือได้ทันที ไม่ต้องมีไลเซนส์ซอฟต์แวร์ราคาแพง
+4. **Universal Bridge & Dual Representation:** ตัวกลางเชื่อมโยง 2D, 3D (SketchUp/Blender), และ IFC โดยผสมผสาน 90% Primitives สำหรับคำนวณโครงสร้างและ BOQ + 10% Baked GLB Asset สำหรับงานสถาปัตย์ประณีต
+5. **Human & AI Super-Collaboration:** ออกแบบให้มี Explicit Uncertainty (`review_status: needs_review`) ให้มนุษย์และ AI ร่วมมือกันตรวจและเติมเต็มสเปกได้อย่างไร้รอยต่อ
+
+---
+
+## 🤖 AI-Agent Installation (ติดตั้งง่ายที่สุดในโลกด้วย AI ของคุณ)
+
+If you use an AI coding assistant (like **Antigravity, Cursor, Claude Code, Jules, or ChatGPT/Copilot**), you don't even need to install it manually!
+
+Just copy and send this prompt to your AI:
+
+> *"Please read https://github.com/PRIDA-TAKON/debim and `AGENTS.md`, install debim in my environment, and run `debim --help` to verify."*
+
+Your agent will inspect the repository, install the dependencies, and verify everything automatically.
+
+---
+
+## 🚀 Manual Quickstart
+
+### 1. Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/PRIDA-TAKON/debim.git
+cd debim
+
+# Install in editable mode
+pip install -e .
+
+# Or with full dev & IFC compiler tools
+pip install -e ".[ifc,dev]"
+```
+
+### 2. Basic Commands
+
+```bash
+# Initialize a new project
+debim init my-project
+
+# Validate schema syntax & grid references
+debim validate -m examples/farnsworth_house/project.yaml
+
+# Run automated building code compliance checks (pytest)
+debim test
+
+# Calculate Quantitative Take-Off (Steel weight, stone volume, glass area)
+debim qto -m examples/farnsworth_house/project.yaml
+
+# Generate project-scoped price template with international classifications
+debim cost template -m examples/farnsworth_house/project.yaml -o prices.template.yaml
+
+# Estimate project budget & export BOQ to CSV
+debim cost -m examples/farnsworth_house/project.yaml -p examples/farnsworth_house/prices.yaml -o dist/boq.csv
+
+# Scaffold a new BIM element class boilerplate
+debim scaffold element IfcRailing
+
+# Preview 3D model in your browser (Three.js with Hierarchical Layer Explorer)
+debim view -m examples/farnsworth_house/project.yaml
+
+# Compile declarative YAML to standard IFC4 building model
+debim compile -m examples/farnsworth_house/project.yaml -o dist/farnsworth_house.ifc
+```
+
+---
+
+## 🏗️ Example `project.yaml`
+
+```yaml
+schema: IFC4-Minimal
+project:
+  id: PRJ-2026-001
+  name: "Townhouse-Feasibility"
+  units: { length: METER, area: SQUARE_METER, volume: CUBIC_METER }
+
+# 1. Spatial Structure
+spatial_structure:
+  storeys:
+    - id: L1
+      name: "Level 1"
+      elevation: 0.00
+      height: 3.50
+    - id: L2
+      name: "Level 2"
+      elevation: 3.50
+      height: 3.20
+
+# 2. Reference Grid Axes
+grids:
+  axes_x: { A: 0.00, B: 4.00, C: 8.00 }
+  axes_y: { 1: 0.00, 2: 5.00, 3: 10.00 }
+
+# 3. Materials
+materials:
+  - id: CONC_240
+    name: "Concrete 240 ksc"
+    category: concrete
+    unit_cost_ref: "MAT-CONC-01"
+  - id: AAC_75
+    name: "AAC Block 7.5cm"
+    category: masonry
+    unit_cost_ref: "MAT-AAC-01"
+
+# 4. Elements
+elements:
+  # Column placed at grid intersection [A, 1]
+  - class: IfcColumn
+    tag: C-A1
+    material: CONC_240
+    profile: { shape: BOX, width: 0.20, depth: 0.20 }
+    placement:
+      grid: [A, 1]
+      base_storey: L1
+      top_storey: L2
+    reinforcement:
+      main: "4-DB16"
+      stirrups: "RB6 @ 0.15m"
+
+  # Beam spanning between [A, 1] and [B, 1]
+  - class: IfcBeam
+    tag: B-A1_B1
+    material: CONC_240
+    profile: { shape: BOX, width: 0.20, depth: 0.40 }
+    placement:
+      from_grid: [A, 1]
+      to_grid: [B, 1]
+      storey: L2
+    reinforcement:
+      main_top: "2-DB16"
+      main_bottom: "3-DB20"
+      stirrups: "RB9 @ 0.15m"
+
+  # Wall with door host-child relationship
+  - class: IfcWall
+    tag: W-A1_A2
+    material: AAC_75
+    thickness: 0.075
+    height: 3.10
+    placement:
+      from_grid: [A, 1]
+      to_grid: [A, 2]
+      storey: L1
+    children:
+      - class: IfcDoor
+        tag: D1
+        dimensions: { width: 0.90, height: 2.00 }
+        offset_distance: 1.20
+```
+
+---
+
+## 🔬 Empirical Research & Benchmark (การทดสอบระดับอุตสาหกรรม)
+
+debim ให้ความสำคัญกับความถูกต้องทางวิศวกรรมและการทดสอบแบบเปิดเผย ตรวจสอบซ้ำได้จริง (100% Reproducible Open Science) บน **Kaggle Cloud Multi-Core Benchmark Suite**:
+
+### 1. ⚖️ 3D Visual Regression & Alignment Benchmark (255 อาคารจริงสากล)
+
+<p align="center">
+  <a href="https://www.kaggle.com/code/pridatakon/debim-3d-visual-balanced-benchmark">
+    <img src="https://img.shields.io/badge/Kaggle-Run%20Reproducible%20Benchmark-20BEFF?logo=kaggle&style=for-the-badge" alt="Kaggle Benchmark" />
+  </a>
+</p>
+
+การทดสอบความแม่นยำด้านเรขาคณิต 3 มิติ (3D Visual Fidelity) แบบปิดตาเทียบกับ IFC ต้นฉบับผ่าน **Geometry Variant Deduplication + Balanced Macro-Averaging** บน 4,695 ชิ้นส่วนตัวแทน:
+
+- **🎯 85.50% Median Visual Fidelity:** ทะลุเกณฑ์มาตรฐานสากล ($\ge 85\%$) ครอบคลุมเกินกึ่งหนึ่งของโมเดลทดสอบ
+- **🏗️ 89.07% Structural Match:** งานโครงสร้างรับแรงหลัก (เสา คาน ผนัง ฐานราก) มีความเสถียรระดับเกรด A+
+- **⚡ 82.64% MEP System Match:** งานระบบท่อ ระบบปรับอากาศ และอุปกรณ์ไฟฟ้าอยู่ในตำแหน่งและระนาบที่ถูกต้อง
+
+#### 📈 วิวัฒนาการเปรียบเทียบข้าม 3 เจเนอเรชัน (Progression Across Waves):
+
+| ตัวชี้วัดสากล (Global Metric) | V1 (Baseline) | V2 (Wave 1-2) | V3 (Wave 4 ล่าสุด) | $\Delta$ พัฒนาขึ้นสะสม |
+|---|:---:|:---:|:---:|:---:|
+| **🎯 Median Visual Match (ค่ามัธยฐาน)** | 80.90% | 84.90% | **85.50%** | 🏆 **+4.60% (ทะลุเป้า 85%)** |
+| **⚖️ Macro Average Visual Match** | 70.57% | 77.60% | **77.71%** | 🟢 **+7.13%** |
+| **📊 Micro Average Visual Match** | 72.24% | 80.35% | **80.46%** | 🟢 **+8.23%** |
+| **ชิ้นส่วนที่ผ่านเกณฑ์ ($\ge 85\%$)** | 2,865 ชิ้น | 3,140 ชิ้น | **3,135 ชิ้น** | 🟢 **+270 ชิ้น** |
+| **หมวดหมู่งานระบบและตกแต่งที่ก้าวกระโดด** | | | | |
+| • *ฝ้าเพดาน (`IfcCovering`)* | 11.4% | 89.0% | **89.0%** | 🟢 **+77.6% (ผ่านเกณฑ์)** |
+| • *วาล์วระบบท่อ (`IfcValve`)* | 0.0% | 82.2% | **82.4%** | 🟢 **+82.4% (พุ่งจากศูนย์)** |
+| • *แผ่นเหล็กโครงสร้าง (`IfcPlate`)* | 10.2% | 88.9% | **87.1%** | 🟢 **+76.9% (ผ่านเกณฑ์)** |
+| • *เหล็กค้ำยันเฉียง (`IfcMember`)* | 91.8% | 91.6% | **92.4%** | 🟢 **+0.8% (3D Vector Pitch)** |
+
+👉 *ต้องการตรวจสอบการทดลองเชิงลึกหรือรันซ้ำด้วยตนเอง? ดูโค้ดและดาต้าเซ็ตได้ที่ [Kaggle Benchmark Notebook](https://www.kaggle.com/code/pridatakon/debim-3d-visual-balanced-benchmark)*
+
+---
+
+### 2. 📦 Roundtrip Retention & Storage Reduction Study (407 อาคารสากล)
+
+debim ได้รับการทดสอบอย่างเข้มงวดกับโมเดลอาคารจริงกว่า **407 โครงการ** (สถาปัตยกรรม โครงสร้าง และ MEP โรงพยาบาล):
+
+- **100.0% Median Retention Rate:** โมเดลส่วนใหญ่สามารถสกัดและ Re-compile กลับสู่มาตรฐาน IFC4 ได้ครบถ้วนทุกชิ้นงาน
+- **91.6% Average Storage Reduction:** ลดขนาดไฟล์จาก IFC ดิบลงเฉลี่ย 91%
+- **558M+ LLM Tokens Saved:** ประหยัดบริบทของโมเดลภาษาไปได้มากกว่า **558,629,804 โทเคน**
+- **100.0% Modern Schema Crash-Resilience:** ไม่พบ Fatal Crash หรือ Unhandled Exception บนมาตรฐาน IFC2X3 และ IFC4
+
+📖 **อ่านรายงานวิจัยฉบับเต็ม:** [debim: An Empirical Study of Declarative Building-as-Code on 407 Heterogeneous Real-World OpenBIM Models](docs/research/2026_empirical_study_407_ifc_models.md)  
+📦 **Kaggle Public Benchmark Dataset:** [debim-5000-ifc-benchmark](https://www.kaggle.com/datasets/pridatakon/debim-5000-ifc-benchmark)  
+⚡ **Kaggle Automated Stress Test:** [debim-ifc-stress-test](https://www.kaggle.com/code/pridatakon/debim-ifc-stress-test)
+
+---
+
+## ❓ Frequently Asked Questions (FAQ)
+
+<details>
+<summary><b>Why YAML instead of JSON, Python, or Excel?</b></summary>
+<br>
+YAML is clean, concise, supports nested hierarchies, and allows comments (essential for architectural notes). Unlike JSON, it has no noisy braces. Unlike Excel, it is 100% Git-friendly, diffable, and conflict-resolvable. It serves as a pure declarative DSL (Domain-Specific Language)—just like Kubernetes, Docker Compose, and GitHub Actions.
+</details>
+
+<details>
+<summary><b>How do I place off-grid items (internal partitions, cantilever beams)?</b></summary>
+<br>
+Use relative offsets: `placement: { grid: [A, 1], offset: [1.20, 0.50] }`. Just like pulling a tape measure on site from the nearest grid line.
+</details>
+
+<details>
+<summary><b>Does this replace Revit or AutoCAD?</b></summary>
+<br>
+No, it complements them. debim handles the early-stage upstream workload: rapid feasibility, parametric sizing, AI generation, instant QTO/costing, and automated building law validation. Once validated, run <code>debim compile</code> to export standard IFC4 and load it directly into BlenderBIM, FreeCAD, or Revit for 2D drafting and detail annotations.
+</details>
+
+---
+
+## 📄 License & Attribution
+
+- **Software Code:** Licensed under the [MIT License](LICENSE) — Copyright (c) 2026 Prida Takon.
+- **Research & Technical Reports:** Licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
+- **Benchmark Datasets & Sample Models:** Test fixtures in `tests/fixtures/` originate from [buildingSMART International](https://github.com/buildingSMART) and the Open IFC Model Repository under CC BY 4.0 / CC-BY-3.0.