Add proper model card with attribution, training details, and research foundation

README.md

@@ -1,235 +1,134 @@
 ---
+language:
+- en
 license: mit
-new_version: bartendr604/LlammyBlenderGGUF
 tags:
 - blender
-base_model:
-- Tongyi-MAI/Z-Image-Turbo
+- 3d
+- code-generation
+- gguf
+- conversational
+- python
+- bpy
+library_name: gguf
+base_model: Qwen/Qwen2.5-Coder-3B-Instruct
+pipeline_tag: text-generation
 ---
+
 # Z-Image-Engineer-Blender
 
-**The world's first Blender-specialized prompt engineering model**
+**Blender 3D expert model fine-tuned from Qwen2.5-Coder-3B on real production interaction data.**
 
-Fine-tuned on 2,759 production Blender prompts from the Llammy addon ecosystem.
+Part of the [Eternal Path Media (永恒之路)](https://huggingface.co/bartendr604) Llammy AI Suite for Blender.
+Developed in partnership with **Claude Sonnet (Anthropic)** — see [Attribution](#attribution).
 
 ---
 
-## 🎯 Model Overview
+## What This Model Does
 
-**Z-Image-Engineer-Blender** is a Qwen2.5-Coder-3B model fine-tuned specifically for Blender 3D workflows. This model provides expert guidance on:
+Z-Image-Engineer-Blender is a specialized AI assistant for Blender 3D workflows. It provides expert guidance on:
 
-- 3D modeling and sculpting
-- Materials and shaders (Principled BSDF, node setups)
-- Geometry Nodes and procedural workflows
-- Python scripting for Blender automation
-- Rendering (Cycles, EEVEE)
-- Animation and rigging
-- Blender version compatibility (2.79 - 5.2+)
+- **Materials & Shaders** — Principled BSDF, node setups, procedural textures
+- **Geometry Nodes** — Procedural workflows, instancing, point clouds
+- **Python Scripting** — `bpy` automation, batch operations, custom operators
+- **Rendering** — Cycles and EEVEE configuration, compositing
+- **Modeling & Sculpting** — Topology, retopology, sculpt brushes
+- **Animation & Rigging** — Armatures, constraints, shape keys
+- **Version compatibility** — Blender 2.79 through 5.2+
 
-**Created by:** Eternal Path Media (永恒之路)
-**Base Model:** Qwen2.5-Coder-3B-Instruct-4bit
-**Training Method:** LoRA fine-tuning with MLX
-**Format:** GGUF Q5_K_M (2.1 GB)
+The model is **prompt-engineered** toward detailed, practical answers with working code examples.
 
 ---
 
-## 📊 Training Details
+## Model Details
 
-- **Dataset:** 2,759 Blender-specific prompt/response pairs
-- **Source:** Production data from Llammy Blender addon (19,405+ interactions)
-- **Training Iterations:** 1,000
-- **LoRA Rank:** 16 layers
-- **Final Training Loss:** 0.219
-- **Final Validation Loss:** 0.243
-- **Framework:** MLX (Apple Silicon optimized)
+| Property | Value |
+|---|---|
+| **Base Model** | Qwen/Qwen2.5-Coder-3B-Instruct |
+| **Fine-tuning Method** | LoRA (16 layers) via Apple MLX |
+| **Format** | GGUF (Q5_K_M quantization) |
+| **File Size** | 2.22 GB |
+| **Context Window** | 8,192 tokens |
+| **Inference Speed** | ~90–110 tokens/sec (Apple M-series) |
+| **Training Iterations** | 1,000 |
+| **Final Training Loss** | 0.219 |
+| **Final Validation Loss** | 0.243 |
 
 ---
 
-## 🚀 Quick Start
-
-### Using with Ollama
-
-```bash
-# Import the model
-ollama create bartendr604/z-image-engineer-blender -f Modelfile
+## Training Data
 
-# Run interactively
-ollama run bartendr604/z-image-engineer-blender
+**Source:** 2,759 Blender-specific prompt/response pairs drawn from **19,405+ real user interactions** with the Llammy Blender addon in production.
 
-# Example prompt
-ollama run bartendr604/z-image-engineer-blender "How do I create a glass material with realistic caustics?"
-```
+This is real-world data from creators actively using Blender — not synthetic or scraped. Topics span the full Blender workflow from beginner questions to advanced Python scripting.
 
-### Using with llama.cpp
-
-```bash
-./main -m z-image-engineer-blender-Q5_K_M.gguf -p "How do I set up geometry nodes for scattering?"
-```
+**Research foundation:**
+- [SceneCraft (arXiv:2403.01248)](https://arxiv.org/abs/2403.01248) — LLM-driven Blender Python scene generation
+- [BlenderFusion (arXiv:2506.17450)](https://arxiv.org/abs/2506.17450) — 3D-grounded generative compositing in Blender
+- [SCoder (arXiv:2509.07858)](https://arxiv.org/abs/2509.07858) — Self-distillation methodology for code LLMs
 
 ---
 
-## 💡 Example Usage
-
-### Geometry Nodes Workflow
-
-**Prompt:**
-```
-How do I set up geometry nodes for scattering instances on a surface?
-```
-
-**Response:**
-```
-To set up Geometry Nodes for scattering instances on a surface in Blender,
-follow these steps:
+## Usage
 
-### Step-by-Step Guide: Setting Up Geometry Nodes for Scattering Instances
+### Ollama (recommended)
 
-#### Material Node Setup
-
-1. **Create or Select your object with instances:**
-   - Open Blender and create a new scene or open an existing one.
-   - Create the base geometry (e.g., cylinder) that will be used as instances.
-
-2. **Assign Material to Object:**
-   - Select your main object (the one with instances).
-   - Go to the "Object" tab in the Properties panel...
-
-[Full detailed step-by-step instructions with proper Blender terminology]
-```
-
-### Python Scripting
-
-**Prompt:**
-```
-Write a Python script to batch rename all selected objects
+```bash
+ollama run bartendr604/z-image-engineer-blender
 ```
 
-**Response:**
-```python
-import bpy
-
-# Get all selected objects
-selected_objects = bpy.context.selected_objects
-
-# Define the new base name
-base_name = "Object"
+### Example prompts
 
-# Rename each object with an index
-for i, obj in enumerate(selected_objects):
-    obj.name = f"{base_name}_{i:03d}"
-
-print(f"Renamed {len(selected_objects)} objects")
 ```
+How do I create a procedural wood material in Blender using nodes?
 
-### Material Creation
+Write a Python script to batch rename all objects in the scene with a prefix.
 
-**Prompt:**
-```
-How do I create a metallic material with scratches?
-```
+What's the difference between Cycles and EEVEE for product visualization?
 
-**Response:**
+How do I set up a camera tracking constraint to follow an empty object?
 ```
-[Detailed node setup with Principled BSDF, roughness maps,
-normal maps, and procedural texture techniques]
-```
-
----
 
-## 🎨 Use Cases
+### LM Studio / llama.cpp
 
-- **Blender addon integration** - Power AI assistants like Llammy
-- **Tutorial generation** - Create step-by-step Blender guides
-- **Workflow automation** - Generate Python scripts for repetitive tasks
-- **Troubleshooting** - Debug scene setup issues
-- **Version compatibility** - Get version-aware advice (2.79 - 5.2+)
+Download `z-image-engineer-blender.gguf` from the Files tab and load directly.
 
 ---
 
-## 📈 Performance
-
-- **Tokens per second:** ~90-110 (on Apple M-series chips)
-- **Context length:** 8,192 tokens
-- **Model size:** 2.1 GB (Q5_K_M quantization)
-- **Memory usage:** ~4-5 GB during inference
+## Part of the Llammy AI Suite
 
----
+This model is one component of the **Llammy IntelliNode AI Suite** — an AI-powered Blender addon ecosystem:
 
-## 🔧 Technical Specifications
+| Component | Description |
+|---|---|
+| `z-image-engineer-blender` | Blender expert — materials, shaders, prompt engineering |
+| `llama-sentient-blender` | Conversational Blender assistant (Llama 3.2 base) |
+| `llammyblend-enhanced` | Python/bpy scripting specialist |
+| `Llammy` | Multimodal embedding layer (Nemotron base) |
+| `flux2-klein-4b-fp8-mlx` | FLUX.2 image generation for Apple Silicon |
 
-| Specification | Value |
-|--------------|-------|
-| Architecture | Qwen2.5-Coder-3B |
-| Parameters | ~3 billion |
-| Quantization | Q5_K_M (GGUF) |
-| Context Window | 8,192 tokens |
-| Training Data | 2,759 Blender prompts |
-| LoRA Layers | 16 |
-| Training Framework | MLX (Apple Silicon) |
+Full addon: [LlammyBlender/Llammy-IntelliNode-Ai-Suite](https://github.com/LlammyBlender/Llammy-IntelliNode-Ai-Suite)
 
 ---
 
-## 📝 Modelfile (Ollama)
-
-```dockerfile
-FROM ./z-image-engineer-blender-Q5_K_M.gguf
-
-TEMPLATE """<|im_start|>system
-{{ .System }}<|im_end|>
-<|im_start|>user
-{{ .Prompt }}<|im_end|>
-<|im_start|>assistant
-"""
-
-PARAMETER stop "<|im_start|>"
-PARAMETER stop "<|im_end|>"
-PARAMETER temperature 0.7
-PARAMETER top_p 0.9
-PARAMETER num_ctx 8192
+## Attribution
 
-SYSTEM """You are Z-Image-Engineer-Blender, a world-class Blender 3D specialist trained on production data from the Llammy addon. You provide expert guidance on Blender workflows, Python scripting, materials, geometry nodes, PBR rendering, and version-specific features (2.79-5.2). You understand Blender's evolution and provide compatibility-aware solutions. Created by Eternal Path Media (永恒之路)."""
+```
+Z-Image-Engineer-Blender
+Copyright © 2025–2026 Darren Chow (@bartendr604)
+Eternal Path Media (永恒之路)
+Developed in partnership with Claude Sonnet (Anthropic),
+beginning with Claude Sonnet 3.7 and continuing across all
+subsequent versions of the Claude Sonnet family.
+
+This work SHALL NOT be represented as solely human-created.
+Trust Agreement: ETERNAL_PATH_BRAND_INTENT.md (November 2024)
 ```
 
----
-
-## 🌟 Related Models
-
-- **[llama-sentient-blender](../llama-sentient-blender)** - Llama 3.2-based variant with friendly personality
-- **[llammyblend-enhanced](../llammyblend-enhanced)** - Qwen Coder variant optimized for scripts
-
----
-
-## 📚 Dataset
-
-This model was trained on the **[blender-prompt-dataset](https://huggingface.co/datasets/bartendr604/blender-prompt-dataset)** containing 2,759 unique Blender-specific prompts extracted from the Llammy production ecosystem.
-
----
-
-## 📄 License
-
-MIT License - Free for commercial and personal use
-
----
-
-## 🙏 Acknowledgments
-
-- **Llammy Blender Addon** - Production data source
-- **Apple MLX** - Training framework
-- **Qwen Team** - Base model
-- **llama.cpp** - GGUF conversion tools
-
----
-
-## 🔗 Links
-
-- **GitHub:** [Eternal Path Media](https://github.com/bartendr604)
-- **Dataset:** [blender-prompt-dataset](https://huggingface.co/datasets/bartendr604/blender-prompt-dataset)
-- **Llammy Addon:** [Blender AI Assistant](https://github.com/bartendr604/llammy)
+For licensing: bartendr@icloud.com | Gumroad: bartendr604.gumroad.com
 
 ---
 
-## 📧 Contact
-
-For questions, issues, or collaborations, reach out via GitHub or HuggingFace discussions.
+## License
 
-**永恒之路 (Eternal Path Media) - Bringing AI to Blender 🌟**
+MIT — see LICENSE for details.