Update README.md

README.md

@@ -1,184 +1,180 @@
----
-base_model: unsloth/gemma-3n-e4b-it-unsloth-bnb-4bit
-tags:
-- text-generation-inference
-- transformers
-- unsloth
-- gemma3n
-- trl
-license: apache-2.0
-language:
-- en
----
-
-# C3D-v0: Text-to-CadQuery Model
+# C3D-v0: AI-Powered CAD Code Generation Model
 
-A fine-tuned Gemma3N model that generates Python CadQuery scripts from natural-language descriptions. C3D-v0 enables you to go from “a simple gear with 12 teeth” to runnable CadQuery code in one prompt.
-
----
+**Fine-tuned Gemma 3n model for generating CADQuery Python code from natural language descriptions**
 
 ## Model Description
 
-C3D-v0 is built on top of the **unsloth/gemma-3n-E4B-it** base model and fine-tuned on the [Text-to-CadQuery dataset](https://github.com/Text-to-CadQuery/Text-to-CadQuery) using LoRA. It excels at translating high-level CAD intents into valid CadQuery Python scripts.
-
-* **Base model**: `unsloth/gemma-3n-E4B-it`
-* **Fine-tuning method**: LoRA via Unsloth + Hugging Face `SFTTrainer`
-* **Training data**: \~48 000 prompt–script pairs (50 % of Text-to-CadQuery train split)
-* **Chat template**: `"gemma-3"` instruction/completion style
-* **Context window**: up to 32 k tokens
+C3D-v0 is a specialized language model fine-tuned for generating 3D CAD models through Python code. Built on Google's Gemma 3n architecture, this model transforms natural language descriptions into executable CADQuery scripts that can be rendered as 3D models.
 
----
+This model is part of the [C3D project](https://github.com/unxversal/c3d) - a complete text-to-CAD pipeline featuring an interactive CLI, 3D web viewer, and local AI inference.
 
-## Usage
+## Key Features
 
-### Installation
+- 🎯 **Specialized for CAD**: Fine-tuned specifically on CAD generation tasks
+- 🔧 **CADQuery Focus**: Generates clean, executable Python CADQuery code
+- 🚀 **Local Inference**: Designed to run locally via Ollama
+- 📐 **3D Understanding**: Trained on geometric and mechanical design concepts
+- ⚡ **Optimized Performance**: GGUF quantized for efficient inference
 
-```bash
-# If you’re using Hugging Face Transformers
-pip install transformers accelerate
+## Training Details
 
-# If you want Ollama integration
-brew install ollama
-ollama pull numinousmuses/C3D-v0
-```
+### Base Model
+- **Architecture**: Google Gemma 3n (4B parameters)
+- **Base Model**: `unsloth/gemma-3n-E4B-it`
 
-### Inference (Transformers)
+### Dataset
+- **Source**: [Text-to-CadQuery Dataset](https://github.com/Text-to-CadQuery/Text-to-CadQuery)
+- **Training Size**: ~48,000 examples (50% of full dataset)
+- **Validation**: Full validation set maintained
 
-```python
-from transformers import AutoTokenizer, AutoModelForCausalLM, TextStreamer
+### Training Configuration
+- **Method**: LoRA (Low-Rank Adaptation) fine-tuning
+- **Epochs**: 1 (due to resource constraints)
+- **Batch Size**: 2 per device, 4 gradient accumulation steps
+- **Learning Rate**: 2e-4
+- **Platform**: Trained on Kaggle/Colab free tier
 
-model_id = "numinousmuses/C3D-v0"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model     = AutoModelForCausalLM.from_pretrained(model_id)
+## Usage
 
-prompt = "Generate a simple cube in CadQuery."
+### Via Ollama (Recommended)
 
-# Prepare input using the same chat template
-inputs = tokenizer(
-    f"<start_of_turn>user\n{prompt}",
-    return_tensors="pt"
-)
+```bash
+# Install the model
+ollama pull joshuaokolo/C3Dv0
 
-# Streamed generation
-streamer = TextStreamer(tokenizer, skip_prompt=True)
-model.generate(
-    **inputs,
-    max_new_tokens=512,
-    temperature=0.7,
-    top_p=0.9,
-    streamer=streamer
-)
+# Generate CAD code
+ollama run joshuaokolo/C3Dv0 "Create a simple gear with 12 teeth"
 ```
 
-### Inference (Pipeline)
+### Via C3D CLI (Full Experience)
 
-```python
-from transformers import pipeline
+```bash
+# Install C3D
+npm install -g c3d
 
-generator = pipeline(
-    "text-generation",
-    model="numinousmuses/C3D-v0",
-    tokenizer="numinousmuses/C3D-v0",
-    device=0  # set to GPU if available
-)
+# Generate with interactive 3D viewer
+c3d generate "a phone case for iPhone 15"
+```
 
-cad_script = generator(
-    "Generate a parametric bracket with two mounting holes.",
-    max_new_tokens=400,
-    temperature=0.8,
-    top_p=0.95
-)[0]["generated_text"]
+### Direct Model Usage
 
-print(cad_script)
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+import torch
+
+# Load model and tokenizer
+model_name = "numinousmuses/C3D-v0"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(model_name)
+
+# Generate CAD code
+prompt = "Create a simple rectangular bracket"
+inputs = tokenizer(prompt, return_tensors="pt")
+
+with torch.no_grad():
+    outputs = model.generate(
+        **inputs,
+        max_new_tokens=512,
+        temperature=0.8,
+        top_p=0.9,
+        do_sample=True
+    )
+
+generated_code = tokenizer.decode(outputs[0], skip_special_tokens=True)
+print(generated_code)
 ```
 
-### Inference (Ollama)
+## Prompt Format
 
-```bash
-# Start Ollama daemon if not running
-ollama serve &
+The model works best with direct, descriptive prompts:
 
-# Run a chat prompt
-ollama chat numinousmuses/C3D-v0 \
-  --prompt "Generate a hollow cylinder with radius=5, height=10."
+```
+"Create a simple gear with 12 teeth"
+"Generate a phone case for iPhone 15"
+"Make a rectangular bracket with mounting holes"
+"Design a simple pulley with a 50mm diameter"
 ```
 
----
+## Model Performance
 
-## Example
+- **Context Length**: Up to 32k tokens (though trained at 16k)
+- **Code Quality**: Generates syntactically correct CADQuery code
+- **Geometric Understanding**: Handles basic to intermediate 3D shapes
+- **Memory Usage**: ~10GB RAM for full context inference
 
-```bash
-$ c3d generate "a gear with 12 teeth, outer diameter 50mm, thickness 5mm"
-```
+## Example Output
 
-**Output snippet:**
+**Input**: "Create a simple gear with 12 teeth"
 
+**Output**:
 ```python
-from cadquery import Workplane
-
-# Parameters
-num_teeth    = 12
-outer_dia    = 50
-tooth_angle  = 360 / num_teeth
-thickness    = 5
+import cadquery as cq
 
+# Create a gear with 12 teeth
 gear = (
-    Workplane("XY")
-    .circle(outer_dia / 2)
-    .extrude(thickness)
-    .faces(">Z")
-    .workplane()
-    .polarArray(0, 0, outer_dia / 2 - 2, num_teeth)
-    .circle(2)
-    .cutThruAll()
+    cq.Workplane("XY")
+    .circle(25)  # Outer radius
+    .circle(20)  # Inner radius for teeth
+    .extrude(5)  # Thickness
 )
-gear.val().exportStl("gear.stl")
-```
 
----
-
-## Training Details
-
-* **Trainer**: `trl.SFTTrainer` with 4 bit base + LoRA adapters
-* **Batch size**: 2 per device, gradient accumulation 4 (effective 8)
-* **Epochs**: 1 (due to resource limits)
-* **Learning rate**: 2 × 10⁻⁴ with linear scheduler and 5 warmup steps
-* **Checkpoints** saved every 1 000 steps; max 2 retained
-* **NaNGuard & TimeLimitCallback** to ensure stability & limit 11 h runtime
-
----
+# Add teeth around the circumference
+for i in range(12):
+    angle = i * 30  # 360/12 = 30 degrees
+    tooth = (
+        cq.Workplane("XY")
+        .transformed(rotate=(0, 0, angle))
+        .rect(3, 8)
+        .extrude(5)
+    )
+    gear = gear.union(tooth)
+
+result = gear
+```
 
 ## Limitations
 
-* May occasionally produce scripts with minor syntax errors—verify before rendering.
-* Lacks vision input support (text-only).
-* Trained on a subset of examples; complex assemblies may require manual edits.
-
----
+- **Training Scope**: Limited to 50% of dataset due to resource constraints
+- **Complexity**: Best suited for simple to moderate complexity objects
+- **Vision**: Text-only model (multimodal version planned)
+- **Domain**: Focused on mechanical/geometric objects from training data
 
 ## Roadmap
 
-1. **Full-dataset fine-tuning** (all \~99 000 examples).
-2. **Multimodal support** (image → 3D model).
-3. **Iterative verify-and-refine loop** with automatic render feedback.
+- 🔄 **Full Dataset Training**: Complete training on entire dataset
+- 👁️ **Multimodal Support**: Image-to-CAD generation capabilities
+- 🎯 **Improved Prompting**: Enhanced prompt engineering for better results
+- 📈 **Performance Optimization**: Additional fine-tuning iterations
 
----
+## Related Links
 
-## Citation
+- **Main Project**: [C3D on GitHub](https://github.com/unxversal/c3d)
+- **Ollama Model**: [joshuaokolo/C3Dv0](https://ollama.com/joshuaokolo/C3Dv0)
+- **GGUF Version**: [C3D-v0-gguf](https://huggingface.co/numinousmuses/C3D-v0-gguf)
+- **Dataset**: [Text-to-CadQuery](https://github.com/Text-to-CadQuery/Text-to-CadQuery)
 
-If you use C3D-v0 in your work, please cite:
+## Citation
 
 ```bibtex
-@misc{Okolo2025C3Dv0,
-  title        = {C3D-v0: Text-to-CadQuery AI Model},
-  author       = {Okolo, Joshua},
-  year         = {2025},
-  howpublished = {\url{https://huggingface.co/numinousmuses/C3D-v0}},
+@misc{c3d-v0-2024,
+  title={C3D-v0: AI-Powered CAD Code Generation},
+  author={Joshua Okolo},
+  year={2024},
+  url={https://github.com/unxversal/c3d}
 }
 ```
 
----
+## Acknowledgments
+
+- **Google DeepMind**: For the Gemma 3n base model and competition opportunity
+- **Unsloth**: For providing efficient fine-tuning infrastructure
+- **Text-to-CadQuery Team**: For the comprehensive training dataset
+- **Ollama**: For local inference capabilities
 
 ## License
 
 Apache 2.0
+
+---
+
+**Contact**: Joshua Okolo | Mechanical Engineering + Computer Science @ Harvard | [Portfolio](https://bento.me/joshuaokolo)