Add model card

README.md

@@ -0,0 +1,230 @@
+---
+license: llama3.2
+base_model: huihui-ai/Llama-3.2-3B-Instruct-abliterated
+tags:
+  - mlx
+  - lora
+  - firearms
+  - ar-15
+  - armorer
+  - apple-silicon
+  - fine-tuned
+  - abliterated
+pipeline_tag: text-generation
+language:
+  - en
+model-index:
+  - name: AR15_Expert_Larry_3B_4bit
+    results: []
+---
+
+# 🔫 AR-15 Expert Armorer — 3B 4-bit (Apple MLX)
+
+A purpose-built AR-15 armorer assistant fine-tuned on Apple Silicon using MLX LoRA. Designed for **fully offline** use on M-series Macs with as little as 8GB RAM.
+
+This model was trained by a veteran firearms enthusiast to serve as a portable reference for AR-15/M16 platform maintenance, troubleshooting, and history. It runs entirely on-device with zero cloud dependency.
+
+---
+
+## Model Details
+
+### Description
+
+This is a 2-pass LoRA fine-tune of [huihui-ai/Llama-3.2-3B-Instruct-abliterated](https://huggingface.co/huihui-ai/Llama-3.2-3B-Instruct-abliterated) — an uncensored variant of Meta's Llama 3.2 3B Instruct model. The abliteration removes RLHF refusal behaviors, allowing the model to discuss firearms maintenance without triggering safety filters.
+
+The fine-tuning was performed using Apple's [MLX framework](https://github.com/ml-explore/mlx) with LoRA (Low-Rank Adaptation), making the entire training pipeline native to Apple Silicon with zero CUDA dependency.
+
+### Key Capabilities
+
+| Domain | Coverage |
+|--------|----------|
+| **Design History** | Eugene Stoner's direct impingement philosophy, ArmaLite origins, military adoption timeline (M16/M16A1/M4), civilian AR-15 evolution |
+| **Field Stripping** | Complete step-by-step disassembly and reassembly procedures |
+| **Cleaning & Maintenance** | Lubrication points, carbon removal, bore cleaning, inspection schedules, recommended solvents and oils |
+| **Parts Identification** | Bolt carrier group components, buffer system (H/H2/H3 buffers), gas block types, barrel profiles, handguard systems |
+| **Troubleshooting** | Failure to feed (FTF), failure to eject (FTE), double feeds, short-stroking, over-gassing, light primer strikes |
+| **Gas System** | Direct impingement vs gas piston, gas tube alignment, gas ring inspection, port sizing |
+| **Barrel & Accuracy** | Twist rates (1:7, 1:8, 1:9), chrome lining vs stainless, headspace gauging, barrel break-in |
+| **Legal Context** | M16 vs AR-15 fire control group differences, NFA considerations (informational only) |
+
+### Intended Use
+
+- **Primary:** Offline armorer's reference for AR-15 platform owners
+- **Secondary:** Educational tool for understanding the M16/AR-15 design lineage
+- **Hardware target:** M1 Mac with 8GB RAM (minimum viable)
+
+### Out of Scope
+
+- This model is NOT a substitute for professional armorer training or manufacturer documentation
+- It should NOT be used for legal advice regarding firearms regulations
+- It may occasionally hallucinate specific torque values or part numbers — always verify against official TM/FM manuals
+
+---
+
+## Technical Specifications
+
+| Specification | Value |
+|---------------|-------|
+| **Architecture** | LlamaForCausalLM (3.2B parameters) |
+| **Base Model** | huihui-ai/Llama-3.2-3B-Instruct-abliterated |
+| **Fine-Tuning Method** | LoRA (Low-Rank Adaptation) via MLX |
+| **Training Passes** | 2 (1000 total iterations) |
+| **Quantization** | 4.5-bit (MLX native) |
+| **Model Size** | 1.7 GB on disk |
+| **Peak Inference RAM** | ~2 GB |
+| **Inference Speed (M1 8GB)** | ~60-80 tokens/sec |
+| **Inference Speed (M4 Pro 48GB)** | ~115 tokens/sec |
+| **Context Window** | 1024 tokens (effective training length) |
+| **Vocabulary** | 128,256 tokens (Llama 3.2 tokenizer) |
+
+---
+
+## Training Details
+
+### Dataset
+
+- **147 ChatML-formatted Q&A pairs** covering AR-15/M16 technical knowledge
+- **17 held-out validation examples**
+- Sources: Publicly available AR-15 armorer's guides, M16 technical manuals, Eugene Stoner design history, and maintenance protocol documentation
+- Format: Standard ChatML (`{"messages": [{"role": "user", ...}, {"role": "assistant", ...}]}`)
+
+### Training Configuration
+
+#### Pass 1 — Foundation
+```
+Iterations: 500
+Batch size: 1
+LoRA layers: 8
+Learning rate: 1e-4
+Max sequence length: 1024
+Trainable parameters: 6.947M (0.216% of 3.2B)
+Starting validation loss: 2.996
+Final train loss: 1.879
+Peak memory: 9.354 GB
+```
+
+#### Pass 2 — Refinement
+```
+Iterations: 500 (resumed from Pass 1 adapter)
+Batch size: 1
+LoRA layers: 8
+Learning rate: 5e-5 (halved for stability)
+Max sequence length: 1024
+Starting train loss: 0.492
+Final train loss: 0.046
+Final validation loss: 2.745
+Peak memory: 9.368 GB
+```
+
+### Training Hardware
+
+- **Device:** Apple MacBook Pro M4 Pro (48GB Unified Memory)
+- **Framework:** MLX v0.31.3 with mlx-lm
+- **Total training time:** ~12 minutes (both passes)
+- **No GPU cluster, no cloud compute** — trained entirely on a laptop
+
+### Loss Progression
+
+```
+Pass 1: 2.996 → 1.997 → 1.742 → 1.278 → 1.164 → 1.879 (500 iters)
+Pass 2: 0.492 → 0.434 → 0.342 → 0.213 → 0.208 → 0.046 (500 iters)
+```
+
+---
+
+## Usage
+
+### Prerequisites
+
+- macOS with Apple Silicon (M1/M2/M3/M4)
+- Python 3.10+
+- `mlx-lm` package
+
+### Installation
+
+```bash
+pip install mlx-lm
+git clone https://huggingface.co/Roderick3rd/AR15_Expert_Larry_3B_4bit
+cd AR15_Expert_Larry_3B_4bit
+```
+
+### Single Prompt
+
+```bash
+python -m mlx_lm.generate \
+    --model . \
+    --prompt "What is the correct procedure for inspecting gas rings on an AR-15 bolt?" \
+    --max-tokens 500
+```
+
+### Interactive Chat
+
+```bash
+python -m mlx_lm.chat --model .
+```
+
+### Python API
+
+```python
+from mlx_lm import load, generate
+
+model, tokenizer = load("Roderick3rd/AR15_Expert_Larry_3B_4bit")
+
+prompt = "Explain Eugene Stoner's direct impingement gas system design."
+response = generate(model, tokenizer, prompt=prompt, max_tokens=500)
+print(response)
+```
+
+---
+
+## Sample Outputs
+
+**Prompt:** "How do I field strip an AR-15?"
+
+> Field stripping an AR-15 involves removing the components from the rifle to make it easier to clean and maintain. The process is relatively simple once you understand the steps involved. Here's a step-by-step guide:
+>
+> 1. **Use a clean surface**: Place the AR-15 on a flat, stable surface...
+> 2. **Remove the forward assist**: Locate the forward assist trigger and move the trigger down...
+> 3. **Remove the handguard**: Locate the handguard and release the lock button...
+> 4. **Remove the charging handle**: Locate the charging handle and release the lock button...
+
+---
+
+## Limitations & Bias
+
+1. **Small model, small dataset:** 3B parameters trained on 147 examples. The model has strong domain knowledge but limited reasoning depth compared to larger models.
+2. **Occasional hallucination:** May fabricate specific part numbers, torque specifications, or military designation details. Always cross-reference with official documentation.
+3. **Repetition at length:** On prompts requiring extended output (>300 tokens), the model may become repetitive. Use `--max-tokens 300` for best results.
+4. **US-centric:** Training data is primarily based on US military and civilian AR-15 documentation.
+5. **No safety filter:** This model is abliterated (safety refusals removed). It will discuss any firearms topic without restriction.
+
+---
+
+## Ethical Considerations
+
+This model provides publicly available firearms maintenance information in a convenient offline format. The same information is freely available in published armorer's manuals, YouTube videos, and manufacturer documentation. This model does not enable any capability that isn't already publicly accessible.
+
+The model is intended for lawful firearms owners performing routine maintenance on legally owned firearms.
+
+---
+
+## Citation
+
+```bibtex
+@misc{ar15expert2026,
+  title={AR-15 Expert Armorer 3B 4-bit},
+  author={Roderick3rd},
+  year={2026},
+  publisher={HuggingFace},
+  url={https://huggingface.co/Roderick3rd/AR15_Expert_Larry_3B_4bit}
+}
+```
+
+---
+
+## Acknowledgments
+
+- **Meta AI** — Llama 3.2 base model
+- **huihui-ai** — Abliterated variant removing RLHF safety filters
+- **Apple MLX Team** — Native Apple Silicon training framework
+- **Eugene Stoner** — For designing the platform this model is about