Update README.md

README.md

@@ -1,3 +1,171 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+language:
+  - en
+tags:
+  - revit
+  - bim
+  - architecture
+  - code-generation
+  - fine-tuned
+  - gguf
+  - construction
+  - aec
+  - autodesk
+base_model: Qwen/Qwen3-14B
+library_name: gguf
+pipeline_tag: text-generation
+---
+
+# revit-coder-14b
+
+A domain-adapted 14B parameter language model fine-tuned for Autodesk Revit 2025+ API development. Generates production-grade C# code with correct transaction management, thread safety patterns, and crash-resistant architecture.
+
+Built on Qwen3-14B using QLoRA. Available in F16 (full precision) and Q4_K_M (quantized) GGUF formats.
+
+## What This Model Does
+
+This model is specialized for Revit API code generation and validation. It understands:
+
+- Transaction hierarchy (Transaction, TransactionGroup, SubTransaction) and when to use each
+- Thread safety with IExternalEventHandler and ExternalEvent patterns
+- IFailuresPreprocessor for agentic/automated execution without modal dialog popups
+- FilteredElementCollector efficiency patterns and filter chaining
+- Batch APIs (NewFamilyInstances2, Delete(ICollection)) for high-performance operations
+- Element lifecycle management and stale reference prevention
+- Revit 2025+ specifics: .NET 8, C# 12, ElementId.Value (long), net8.0-windows targeting
+- Worksharing safety checks and checkout patterns
+- Electrical systems, PanelScheduleView handling, and unit conversion
+
+## Quick Start (Ollama)
+
+Download the Q4_K_M GGUF (recommended for most hardware):
+
+```bash
+# Create a Modelfile
+cat > Modelfile << 'EOF'
+FROM ./revit-coder-14b-Q4_K_M.gguf
+
+TEMPLATE """{{- if .System }}<|im_start|>system
+{{ .System }}<|im_end|>
+{{ end }}<|im_start|>user
+{{ .Prompt }}<|im_end|>
+<|im_start|>assistant
+<think>
+
+</think>
+
+"""
+
+SYSTEM "You are a Revit API specialist for Autodesk Revit 2025+ (.NET 8, C# 12). You generate production-grade C# code that is crash-resistant, transaction-safe, and optimized for agentic execution."
+
+PARAMETER temperature 0.7
+PARAMETER num_ctx 16384
+PARAMETER stop "<|im_end|>"
+PARAMETER repeat_penalty 1.1
+EOF
+
+# Create and run
+ollama create revit-coder-14b -f Modelfile
+ollama run revit-coder-14b "Write code to create 100 structural columns at specified coordinates"
+```
+
+## Available Files
+
+| File | Size | Precision | VRAM Required | Use Case |
+|------|------|-----------|---------------|----------|
+| `revit-coder-14b-Q4_K_M.gguf` | 9 GB | 4-bit quantized | ~12 GB | Recommended for local use |
+| `revit-coder-14b-f16.gguf` | 26 GB | Full FP16 | ~28 GB | Maximum quality, requires 32GB+ RAM |
+
+## Example Outputs
+
+### Transaction Safety
+
+**Prompt:** "What's wrong with this code?"
+```csharp
+for (int i = 0; i < walls.Count; i++)
+{
+    var t = new Transaction(doc);
+    t.Start("Delete");
+    doc.Delete(walls[i].Id);
+    t.Commit();
+}
+```
+
+**Model response identifies:**
+- Anti-pattern: Transaction per loop iteration causes N regenerations instead of 1
+- Missing `using` block (resource leak if exception thrown)
+- Should use batch API: `doc.Delete(wallIds)` in a single Transaction
+- Missing IFailuresPreprocessor (modal dialogs will block execution)
+
+### Batch API Knowledge
+
+**Prompt:** "Create 100 structural columns at XYZ coordinates in Revit 2025"
+
+The model generates code using `doc.Create.NewFamilyInstances2()` (the batch API) rather than looping with individual `NewFamilyInstance()` calls, resulting in 5-15x faster execution with a single regeneration.
+
+### Thread Safety
+
+**Prompt:** "How do I call the Revit API from a background thread?"
+
+The model correctly explains that Revit API is single-threaded and provides the IExternalEventHandler + ConcurrentQueue pattern, warning against Task.Run() or ThreadPool approaches that cause crashes.
+
+## Training Details
+
+- **Base model:** Qwen3-14B
+- **Method:** QLoRA (rank 64, alpha 128)
+- **Training data:** Curated Revit API documentation, code patterns, and domain knowledge
+- **Domains:** Revit C# API, IFC reasoning, APS/Forge schemas
+- **Epochs:** 3
+- **Validation loss:** 0.1586
+- **Hardware:** RunPod GPU cluster
+
+## Recommended System Prompt
+
+For best results, use a system prompt that encodes Revit transaction rules. A comprehensive system prompt is available in the [companion repository](https://github.com/schauh11/revit-trained-llm) under `docs/`.
+
+Key rules to include:
+- Transaction decision tree (dependent ops -> TransactionGroup, batch available -> batch API, otherwise -> single Transaction)
+- Batch size limits (max 50 elements per Transaction, max 10 Transactions per TransactionGroup)
+- Thread safety (IExternalEventHandler only, never background threads)
+- Element lifecycle (store ElementId, never Element; re-fetch after commit)
+- Always include IFailuresPreprocessor for agentic execution
+
+## Hardware Requirements
+
+| Format | Minimum RAM | Recommended | Inference Speed (M1 Max 64GB) |
+|--------|-------------|-------------|-------------------------------|
+| Q4_K_M | 16 GB | 32 GB | ~11 tok/s |
+| F16 | 32 GB | 64 GB | ~7 tok/s |
+
+## Use Cases
+
+- **Revit plugin development:** Generate boilerplate with correct transaction patterns
+- **Code review:** Validate existing Revit API code against best practices
+- **Agentic AI:** Serve as the code generation/validation layer in a Revit automation pipeline
+- **Learning:** Understand Revit API patterns through conversational Q&A
+
+## Limitations
+
+- Specialized for Revit 2025+ (.NET 8). May generate outdated patterns for Revit 2023/2024 (.NET Framework 4.8)
+- Code generation, not execution. Generated code should be reviewed before running in production
+- 14B parameter model. For complex multi-file architectural decisions, pair with a frontier model
+
+## License
+
+Apache 2.0. Based on [Qwen3-14B](https://huggingface.co/Qwen/Qwen3-14B) (Apache 2.0).
+
+## Author
+
+Sanjay Chauhan -- [GitHub](https://github.com/schauh11) | [LinkedIn](https://linkedin.com/in/schauh11)
+
+## Citation
+
+```bibtex
+@misc{chauhan2026revitcoder,
+  title={revit-coder-14b: A Domain-Adapted LLM for Revit API Development},
+  author={Chauhan, Sanjay},
+  year={2026},
+  url={https://huggingface.co/schauh11/revit-coder-14b}
+}
+```