Sparse-AST / BWM: Blender World Model Family

The Sparse-AST / BWM (Blender World Model) family is an open-source suite of specialized neural language and procedural code models optimized for Blender 3D scripting, spatial mathematics, and computational geometry (bpy, mathutils, bmesh, numpy, gpu).

All models are serialized in pure SafeTensors with exact bitwise CPU verification, tied weight preservation, and an accompanying Top-K Mixture-of-Experts (MoE) dynamic router.

🏛️ Model Architecture & Family Manifest

Model	Parameters	Layers	Dimensions ($d/h$)	Native Context	Interpolated Context	Curriculum Loss	Perplexity	Subfolder / Status
Sparse-AST-BWM-3M-32	3,276,368 (4.18M total)	4	256 / 512	64 tokens	Up to 4,096 tokens	`16.2013`	10.87M	`3M-32/` (Available)
Sparse-AST-BWM-10M-32	10,517,352 (11.87M total)	6	384 / 768	64 tokens	Up to 4,096 tokens	`21.2309`	485.17M	`10M-32/` (Available)
Sparse-AST-BWM-100M-32	100,893,176 (103.39M total)	18	704 / 1408	32 tokens	Up to 4,096 tokens	`3.9078`	49.79	`100M-32/` (Available)
Sparse-AST-BWM-200M-32	201,121,072 (204.37M total)	28	800 / 1600	32 tokens	Up to 4,096 tokens	`4.4454`	85.24	`200M-32/` (Available)
Sparse-AST-BWM-200M-512	201,121,072 (~201.1M)	28	800 / 1600	512 tokens	Up to 4,096 tokens	`3.5544`	34.97	`200M-32/` (Trained & Active)
Sparse-AST-BWM-500M-32	501,300,512 (~501.3M)	32	1184 / 2368	1,024 tokens	Up to 4,096 tokens	Foundation	Scale	`500M-32/` (`pending_checkpoint`)
Sparse-AST-BWM-TopK-MoE	33,605 (Router)	--	64	Dynamic	Dynamic	`3.6777`	39.55	`TopK-MoE/` (Active 4-Expert)

🎯 Hard Blender Evals: Ground-Truth Blender 5.1 Execution Benchmark

To evaluate true 3D spatial reasoning, API correctness, and procedural execution, models were evaluated across 5 challenging real-world domains directly inside Blender 5.1.0 (Headless Runtime):

Parametric Involute Gear Topology: bmesh procedural vertex loops, mathematical involute curve teeth, bore extrusion, bevel modifiers, and metallic PBR materials.
Forward Kinematics 3-Link Robot Arm: 4x4 affine transformation matrices (mathutils.Matrix), hierarchical coordinate transformations, yaw/pitch angle decomposition, and cylinder bone links.
Procedural Iridescent PBR Shader Graph: Complete ShaderNodeTree link generation, layer weight / fresnel nodes, color ramps, and emission/metallic mixing.
Sinusoidal Harmonic Motion Animation: Multi-axis trigonometric oscillations keyframed into animation_data and F-curve interpolation.
Spatial BVHTree Ray-Mesh Intersection: Dynamic scene raycasting, bounding volume hierarchies, surface normal projection, and contact indicators.

Benchmark Results

Engine / Model	AST Syntax Pass Rate	Real Blender 5.1 Headless Pass Rate	Objects Generated / Scene	Primary Routing Share
Smart Blender Copilot	100% (5/5)	100% (5/5)	4.0 objects	Deterministic Guardrail
Sparse-AST Top-K MoE (324M)	Dynamic Autocomplete	Valid Geometry Prior	Dynamic	35.7% (200M), 31.2% (3M), 23.4% (10M)
Qwen2.5-Coder 3B (Ollama)	0% (raw prompt)	Requires Copilot Guardrail	N/A	High-Level Ideation & Natural Language

🚀 1-Click 3D Generation & Blender Viewport Execution

The model suite provides an end-to-end interactive workflow directly connected to Blender 5.1:

[User Prompt] ──► [Ollama Qwen-3B / Copilot] ──► [Sparse-AST MoE Router]
                                                              │
                                  ┌───────────────────────────┴───────────────────────────┐
                                  ▼                                                       ▼
                       [/run: Interactive 3D]                                 [/render: Headless PNG]
               Opens Blender 5.1 GUI with meshes,                      Renders photorealistic preview
               PBR shaders, lighting, and camera                       image in seconds via Cycles/Eevee

Console Commands (`chat.bat` / `python chat.py`):

/run — Instantly launches the generated script inside Blender 5.1 in full interactive 3D viewport mode.
/render — Renders a high-resolution 3D preview image (.png) in the background and opens it.
/copy — Copies the script to the Windows clipboard for instant Alt+P execution in Blender's Scripting workspace.
/mode — Cycles between Ollama Local LLM, Smart Copilot, and Raw Neural MoE.

🚀 Quick Start & Inference

1. Load Any Specific Model Variant

Using the universal model.py directly from this repository:

from model import SparseASTUniversal

# Load 200M Foundation Model on GPU or CPU
model, config = SparseASTUniversal.from_pretrained(".", subfolder="200M-32", device="cuda")

# Extend context window to 4K tokens at inference time via 1D linear interpolation
model_4k, _ = SparseASTUniversal.from_pretrained(".", subfolder="200M-32", target_context=4096)

2. Autoregressive Code Generation

output = model.generate(prompt="import bpy\nimport bmesh\n", max_new_tokens=128, temperature=0.2)
print(output)

3. Run the Top-K MoE Ensemble Router

from model import MoEEnsembleUniversal

# Dynamically routes across active 3M, 10M, 100M, and 200M experts
moe = MoEEnsembleUniversal.from_pretrained(".")
output = moe.generate_routed("bpy.ops.mesh.primitive_cube_add(", top_k=2)

🤝 Hybrid Architecture: Pairing Sparse-AST with Local Pretrained LLMs (via Ollama)

While general-purpose code LLMs (such as Qwen2.5-Coder:3B or 7B) excel at high-level reasoning and natural language prompt decomposition, compact models frequently hallucinate deprecated Blender API operators (e.g. 2.79 syntax in Blender 4.x/5.x), output syntax fragments, or struggle with complex 3D vector rotation matrices (mathutils.Euler, quaternions, and SLERP).

By pairing a local LLM via Ollama (specifically qwen2.5-coder:3b) with the Sparse-AST / BWM model family & AST Guardrail Engine, you create an ultra-low-latency, zero-leak Local 3D Copilot:

                       ┌────────────────────────────────────────────────────────┐
                       │ User Prompt ("Create a procedural gear with 18 teeth") │
                       └──────────────────────────┬─────────────────────────────┘
                                                  │
                                                  ▼
                               ┌─────────────────────────────────────┐
                               │    Local Pretrained LLM (Ollama)    │
                               │        (qwen2.5-coder:3b)           │
                               │   * 50.5 tokens/sec on GTX 1650     │
                               │   * High-Level Logic & Architecture │
                               │   * Parameter Extraction            │
                               └──────────────────┬──────────────────┘
                                                  │
                                                  ▼
                               ┌─────────────────────────────────────┐
                               │  Sparse-AST / BWM Top-K MoE Experts │
                               │  * 100M Expert: Vector & Mathutils  │
                               │  * 200M Expert: Procedural Geometry │
                               │  * AST Linter & Syntax Guardrail    │
                               └──────────────────┬──────────────────┘
                                                  │
                                                  ▼
                               ┌─────────────────────────────────────┐
                               │  Production-Ready Blender 3D Script │
                               │  * 100% Valid Runnable Python (.py) │
                               │  * Auto-Saved & Copied to Clipboard │
                               │  * 1-Click Blender 5.1 /run & /render│
                               └─────────────────────────────────────┘

1. Benchmark & Hardware Footprint (Locally Measured)

Tested on standard consumer hardware (AMD Ryzen 5 5600H, NVIDIA GeForce GTX 1650 4GB):

Model: qwen2.5-coder:3b (Q4_K quantized GGUF via Ollama)
VRAM Footprint: ~1.83 GB (Leaves >2.1 GB VRAM free for Blender viewport rendering)
Prompt Evaluation: 153.3 tokens/second
Autoregressive Generation: 50.5 tokens/second

2. Setup Ollama in 2 Minutes

Download Ollama (Windows / macOS / Linux), then pull the optimized coding model:

# Optimal local model (ultra-fast, 1.8GB VRAM footprint):
ollama run qwen2.5-coder:3b

# Larger alternative for workstations with 8GB+ VRAM:
ollama run qwen2.5-coder:7b

🔒 SafeTensors Numerical Integrity

Every checkpoint in this repository was converted and audited on CPU:

Tied Weights: Word embeddings (e.weight) and LM head (h_out.weight) share identical memory, mapped via SafeTensors metadata metadata={"h.weight": "e.weight"} to eliminate memory duplication or disk corruption.
Bitwise Numerical Equality: Audited against original PyTorch weights; maximum absolute difference is strictly 0.000000.
Zero Retraining or Pruning: All learned tensors are bit-for-bit preserved from their original checkpoints.

Downloads last month: -