TalkToTim

An AI-assisted timber structural design tool for Autodesk Revit. TalkToTim uses a Graph Neural Network (GNN) trained on EC5 structural rules to generate column and beam layouts from architectural BIM context, then writes the result directly back into Revit.

---

What it does

1. Export — extracts the floor boundary, grids, and levels from the active Revit model
2. Generate — builds a structural graph, runs GNN inference, and proposes a timber column and beam layout
3. Write Back — places timber columns and glulam beams into Revit as native family instances
4. Tim Chat — answers questions about the generated structure using the EC5 Eurocode knowledge graph and structural rules

---

Project Structure

TalkToTim_Workflow/
├── src/                        # Active pipeline scripts
│   ├── predict_gnn.py          # GNN inference → proposal.json + approved_layout.json
│   ├── dataset_5.py            # Synthetic dataset generator (30,000 samples)
│   ├── train_gnn_5.py          # GNN trainer
│   ├── structural_rules.py     # EC5 rule-based knowledge graph
│   ├── ec5_checker.py          # EC5 structural checks
│   ├── graph_builder.py        # Builds runtime/graph.json from BIM context
│   ├── graph_retriever.py      # Queries the Eurocode knowledge graph
│   ├── chat_query.py           # Tim Chat backend (LLM + KG context)
│   ├── llm_command.py          # LLM command parser
│   ├── pdf_extractor.py        # Extracts EC5 clauses from PDFs
│   └── structural_types.py     # Structural type taxonomy
│   └── archive/                # Previous dataset and trainer versions
│
├── tools/                      # Utility and diagnostic scripts
│   ├── simulate_perim_failure.py
│   ├── build_graph.py
│   ├── export_gexf.py
│   └── ...
│
├── runs/
│   └── gnn_5/                  # Active model (best_model.pt, checkpoints/)
│
├── data/
│   └── synthetic_5/            # Training data — 30,000 graph/label pairs
│
├── resources/
│   ├── knowledge_graphs/       # eurocode_graph.json, structural_rules_graph.json, etc.
│   ├── knowledge-graph-3d.html # 3D graph visualiser (drag-and-drop JSON)
│   └── sw-design-of-timber-structures-vol1/2/3-2022.pdf
│
├── runtime/                    # Live exchange files (written at run time)
│   ├── bim_context.json        # Extracted from Revit
│   ├── graph.json              # Column/beam candidate graph
│   ├── proposal.json           # Raw GNN probabilities
│   ├── approved_layout.json    # Final keep/remove decisions
│   ├── chat_history.json       # Tim Chat conversation
│   └── chat_response.json      # Latest Tim Chat reply
│
├── pyrevit_extension/          # Revit plugin (pyRevit)
│   └── TimberGNN.extension/
│       └── TalkToTim.tab/
│           └── Generate.panel/
│               ├── 01_ExportContext.pushbutton/
│               ├── 02_ChatAndGenerate.pushbutton/
│               ├── 03_WriteBack.pushbutton/
│               └── 04_TimChat.pushbutton/
│
├── docs/                       # Documentation
│   ├── diagrams/               # Data flow and system diagrams
│   ├── ARCHITECTURE.md
│   ├── ROADMAP.md
│   ├── DATASET_SPEC.md
│   └── dataset_5_constraints.md
│
└── requirements.txt

---

GNN Model

Model	TimberGNN5
Architecture	Input MLP → 2× SAGEConv → Node head + Edge MLP
Parameters	30,850
Node features	17 (position, level, is_perimeter, structural type ×7, tributary area, load, storeys, distance ×3)
Edge features	10 (span, direction, relation type ×5, UDL, utilisation)
Training data	synthetic_5 — 30,000 samples
Best validation F1	0.854 (epoch 40)
Thresholds	node ≥ 0.25, edge ≥ 0.3

---

Structural Knowledge Graph

src/structural_rules.py implements a traversable EC5 rule graph with 5 node types and 7 edge types:

Node types: ec5_clause, property, condition, rule, decision

Rule priority chain (first match wins):

Priority	Rule	Structural Type	Decision
1	Corner required	anchor	KEEP
2	Perimeter required	boundary	KEEP
3	Span critical	span_critical	KEEP
4	Redundant	redundant	REMOVE
5	Load critical	load_critical	KEEP
6	Void frame	void_edge	ASSESS
7	Infill	infill	ASSESS

---

Runtime Data Flow

Revit Model
    │
    ▼
ExportContext (pyRevit)
    │  bim_context.json
    ▼
ChatAndGenerate (pyRevit)
    │  graph.json
    ▼
predict_gnn.py
    │  proposal.json  →  approved_layout.json
    ▼
WriteBack (pyRevit)
    │
    ▼
Revit Model (columns + beams placed)

---

Setup

Python environment (backend):

python -m venv .ttt
.ttt\Scripts\activate
pip install -r requirements.txt

Revit plugin: Install pyRevit, then symlink or copy pyrevit_extension/TimberGNN.extension into your pyRevit extensions folder.

---

Training a new model

# Generate dataset
.ttt\Scripts\python.exe src\dataset_5.py

# Train
.ttt\Scripts\python.exe src\train_gnn_5.py

Checkpoints are saved to runs/gnn_5/checkpoints/. Best model is saved automatically to runs/gnn_5/best_model.pt.

---

EC5 References

• EC5 cl.5.4 — Boundary conditions for structural systems
• EC5 cl.6.1 — Timber member design in bending and shear
• EC5 cl.6.3 — Column buckling and utilisation
• EC5 cl.9.2 — Connection requirements at perimeter nodes