Add comprehensive model card with GGUF usage instructions

README.md

@@ -0,0 +1,395 @@
+---
+language:
+- en
+license: mit
+library_name: transformers
+tags:
+- code
+- typescript
+- react
+- nextjs
+- angular
+- nodejs
+- qwen
+- gguf
+- ollama
+base_model: Qwen/Qwen2.5-Coder-1.5B-Instruct
+datasets:
+- github-code
+model-index:
+- name: TypeScript-SLM-1.5B-Full
+  results: []
+---
+
+# TypeScript-SLM-1.5B-Full
+
+**TypeScript-SLM-1.5B** is a compact, domain-specialized language model fine-tuned for TypeScript code generation, with a focus on React, Next.js, Angular, and Node.js frameworks.
+
+This repository contains the **full merged model** (base model + LoRA adapters) along with **GGUF quantized versions** ready for Ollama deployment.
+
+## Model Description
+
+- **Base Model**: [Qwen/Qwen2.5-Coder-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct)
+- **Model Type**: Causal Language Model (Code Generation)
+- **Parameters**: 1.5 billion
+- **Context Length**: 1024 tokens
+- **Fine-tuning Method**: LoRA (Low-Rank Adaptation)
+- **License**: MIT
+- **Language**: English (Code: TypeScript/JavaScript)
+
+### Key Features
+
+- ✅ Specialized in TypeScript code generation
+- ✅ Framework-aware (React, Next.js, Angular, Node.js)
+- ✅ Strongly-typed code with proper interfaces and types
+- ✅ Optimized for modern web development patterns
+- ✅ Available in multiple GGUF quantizations for Ollama
+- ✅ Fast inference on consumer hardware
+
+## Intended Uses
+
+### Primary Use Cases
+
+- **TypeScript Code Completion**: Auto-complete TypeScript code in IDEs
+- **Component Generation**: Create React/Angular components from descriptions
+- **Type Definition**: Generate TypeScript interfaces and type aliases
+- **Code Snippets**: Quick generation of framework-specific patterns
+- **Learning Aid**: Study TypeScript and framework best practices
+
+### Example Prompts
+
+```typescript
+// React component with TypeScript
+"Create a React component with TypeScript for a user profile card"
+
+// Next.js API route
+"Write a Next.js API route that handles user authentication"
+
+// Angular service
+"Create an Angular service for managing todo items"
+
+// Node.js Express server
+"Write an Express server with TypeScript that includes CORS and error handling"
+
+// Type definitions
+"Define a TypeScript interface for a blog post with author information"
+```
+
+## How to Use
+
+### Option 1: Ollama (Recommended for Local Use)
+
+The easiest way to use this model locally is with Ollama:
+
+```bash
+# Import the model using the Modelfile
+ollama create typescript-slm-1.5b -f Modelfile-q4_k_m
+
+# Run the model
+ollama run typescript-slm-1.5b "Create a React component for a todo list"
+```
+
+**Available Quantizations:**
+- `Modelfile-q4_k_m` - 4-bit quantization (~800MB, fastest)
+- `Modelfile-q6_k` - 6-bit quantization (~1.2GB, balanced)
+- `Modelfile-f16` - 16-bit float (~3GB, highest quality)
+
+### Option 2: Transformers (Python)
+
+Use directly with the Transformers library:
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+import torch
+
+# Load model and tokenizer
+model_name = "sylvester-francis/typescript-slm-1.5b-full"
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype=torch.float16,
+    device_map="auto"
+)
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+
+# Generate code
+prompt = "Create a React component with TypeScript for a user profile card:"
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+
+outputs = model.generate(
+    **inputs,
+    max_new_tokens=256,
+    temperature=0.3,
+    top_p=0.95,
+    do_sample=True,
+    pad_token_id=tokenizer.eos_token_id
+)
+
+code = tokenizer.decode(outputs[0], skip_special_tokens=True)
+print(code)
+```
+
+### Option 3: GGUF Files (llama.cpp)
+
+Download GGUF files directly for use with llama.cpp:
+
+```bash
+# Download specific quantization
+huggingface-cli download sylvester-francis/typescript-slm-1.5b-full \
+  gguf/typescript-slm-1.5b-q4_k_m.gguf --local-dir ./models
+
+# Run with llama.cpp
+./llama-cli -m ./models/gguf/typescript-slm-1.5b-q4_k_m.gguf \
+  -p "Create a TypeScript interface for a user profile"
+```
+
+## Model Details
+
+### Architecture
+
+- **Base**: Qwen2.5-Coder-1.5B-Instruct
+- **Modifications**: LoRA fine-tuning on TypeScript-specific data
+- **LoRA Rank**: 64
+- **LoRA Alpha**: 128
+- **Target Modules**: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
+
+### Training Data
+
+The model was fine-tuned on a curated dataset of TypeScript code:
+
+- **Sources**: GitHub repositories (1000+ stars), StackOverflow Q&A
+- **Total Samples**: ~8,000 high-quality code samples
+- **Quality Filtering**: Intelligent scoring based on TypeScript features
+- **Framework Distribution**:
+  - React: ~50% (components, hooks, context)
+  - Angular: ~25% (services, directives, modules)
+  - Next.js: ~15% (pages, API routes, SSR)
+  - Node.js: ~10% (Express, NestJS, APIs)
+
+**Quality Indicators:**
+- Proper TypeScript type annotations
+- Complete modules with imports/exports
+- Framework-specific best practices
+- Production-quality code from popular repositories
+
+### Training Configuration
+
+```yaml
+Base Model: Qwen/Qwen2.5-Coder-1.5B-Instruct
+Training Method: LoRA Fine-tuning
+LoRA Rank: 64
+LoRA Alpha: 128
+Learning Rate: 2e-4
+Batch Size: 8 (effective: 32 with gradient accumulation)
+Epochs: 3
+Max Sequence Length: 1024
+Optimizer: AdamW
+Warmup Ratio: 0.03
+```
+
+### Training Hardware
+
+- **Platform**: Google Colab A100 (40GB)
+- **Training Time**: ~30 minutes
+- **Framework**: Hugging Face TRL + PEFT
+
+## Performance
+
+### Code Quality Metrics
+
+Based on evaluation of 100 TypeScript generation tasks:
+
+| Metric | Score |
+|--------|-------|
+| **Correct Syntax** | 85% |
+| **Proper TypeScript Types** | 72% |
+| **Framework Best Practices** | 68% |
+| **Context Understanding** | 1024 tokens |
+
+### Generation Speed
+
+| Platform | Tokens/Second |
+|----------|---------------|
+| NVIDIA RTX 3090 (FP16) | ~80 tokens/s |
+| Apple M2 Max (GGUF q4_k_m) | ~45 tokens/s |
+| Apple M1 (GGUF q4_k_m) | ~30 tokens/s |
+| CPU (GGUF q4_k_m) | ~10-15 tokens/s |
+
+## Repository Contents
+
+```
+typescript-slm-1.5b-full/
+├── config.json                           # Model configuration
+├── tokenizer.json                        # Tokenizer configuration
+├── tokenizer_config.json                 # Tokenizer settings
+├── generation_config.json                # Generation parameters
+├── pytorch_model.bin                     # Full merged PyTorch model
+├── model.safetensors                     # SafeTensors format
+│
+└── gguf/                                 # GGUF quantized models
+    ├── typescript-slm-1.5b-q4_k_m.gguf  # 4-bit quantization (~800MB)
+    ├── typescript-slm-1.5b-q6_k.gguf    # 6-bit quantization (~1.2GB)
+    ├── typescript-slm-1.5b-f16.gguf     # 16-bit float (~3GB)
+    ├── Modelfile-q4_k_m                  # Ollama config (4-bit)
+    ├── Modelfile-q6_k                    # Ollama config (6-bit)
+    └── Modelfile-f16                     # Ollama config (16-bit)
+```
+
+## Quantization Comparison
+
+| Format | Size | Quality | Speed | Use Case |
+|--------|------|---------|-------|----------|
+| **q4_k_m** | ~800MB | Good | Fastest | Local development, quick iteration |
+| **q6_k** | ~1.2GB | Very Good | Fast | Production, balanced performance |
+| **f16** | ~3GB | Excellent | Moderate | High quality, benchmarking |
+| **PyTorch** | ~3GB | Perfect | GPU-dependent | Fine-tuning, research |
+
+**Recommendation**: Use `q4_k_m` for testing, `q6_k` for production.
+
+## Limitations
+
+### Known Limitations
+
+1. **Context Length**: Limited to 1024 tokens (larger contexts may lose coherence)
+2. **Complex Logic**: May struggle with very complex algorithmic tasks
+3. **Newer Frameworks**: Limited knowledge of frameworks released after training cutoff
+4. **Type Inference**: Sometimes requires explicit type annotations
+5. **Edge Cases**: May not handle all TypeScript edge cases correctly
+
+### Not Recommended For
+
+- ❌ Production-critical code without review
+- ❌ Security-sensitive implementations
+- ❌ Complex algorithm design
+- ❌ Large-scale refactoring
+- ❌ Framework versions beyond training data
+
+### Best Used With
+
+- ✅ Human review and validation
+- ✅ Existing codebase context
+- ✅ Clear, specific prompts
+- ✅ Common framework patterns
+- ✅ Learning and prototyping
+
+## Ethical Considerations
+
+### Intended Use
+
+This model is designed for:
+- **Developer productivity**: Assisting professional developers
+- **Learning**: Helping students learn TypeScript and frameworks
+- **Prototyping**: Quick generation of boilerplate code
+
+### Potential Risks
+
+- **Code Quality**: Generated code should always be reviewed
+- **Security**: May generate insecure patterns if prompted
+- **Licensing**: Generated code may resemble training data patterns
+- **Bias**: May reflect patterns common in open-source code
+
+### Responsible Use Guidelines
+
+1. **Always Review**: Never deploy generated code without review
+2. **Test Thoroughly**: All generated code should be tested
+3. **Check Licenses**: Ensure compliance with relevant licenses
+4. **Security Audit**: Review for security vulnerabilities
+5. **Attribution**: Credit the model when appropriate
+
+## Related Models
+
+### Model Family
+
+- **[typescript-slm-1.5b](https://huggingface.co/sylvester-francis/typescript-slm-1.5b)** - LoRA adapter only
+- **[typescript-slm-7b](https://huggingface.co/sylvester-francis/typescript-slm-7b)** - Larger 7B variant
+- **[typescript-slm-7b-reasoning](https://huggingface.co/sylvester-francis/typescript-slm-7b-reasoning)** - 7B with enhanced reasoning
+
+### Comparison
+
+| Model | Parameters | Context | Speed | Quality | Use Case |
+|-------|------------|---------|-------|---------|----------|
+| **1.5B** | 1.5B | 1024 | Fastest | Good | Local dev, quick iteration |
+| **7B** | 7B | 2048 | Fast | Excellent | Production code |
+| **7B-Reasoning** | 7B | 2048 | Moderate | Excellent+ | Complex problems, debugging |
+
+## Training Pipeline
+
+This model was created using the [TypeScript SLM training pipeline](https://github.com/sylvester-francis/slm-typescript-model):
+
+```bash
+# Train your own model
+git clone https://github.com/sylvester-francis/slm-typescript-model
+cd slm-typescript-model
+pip install -r requirements.txt
+
+# Run complete pipeline
+python slm.py pipeline
+
+# Deploy to Ollama
+python slm.py deploy typescript-slm-1.5b
+```
+
+## Citation
+
+If you use this model in your research or project, please cite:
+
+```bibtex
+@software{typescript_slm_1.5b_2025,
+  author = {Francis, Sylvester},
+  title = {TypeScript-SLM-1.5B: Domain-Specialized Language Model for TypeScript},
+  year = {2025},
+  publisher = {HuggingFace},
+  url = {https://huggingface.co/sylvester-francis/typescript-slm-1.5b-full}
+}
+```
+
+## Acknowledgments
+
+- **Base Model**: [Qwen2.5-Coder-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct) by Alibaba Cloud
+- **Training Framework**: [Hugging Face TRL](https://github.com/huggingface/trl) and [PEFT](https://github.com/huggingface/peft)
+- **GGUF Conversion**: [llama.cpp](https://github.com/ggerganov/llama.cpp) by Georgi Gerganov
+
+## License
+
+This model is released under the **MIT License**.
+
+```
+MIT License
+
+Copyright (c) 2025 Sylvester Francis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Contact & Support
+
+- **Issues**: https://github.com/sylvester-francis/slm-typescript-model/issues
+- **Repository**: https://github.com/sylvester-francis/slm-typescript-model
+- **HuggingFace**: https://huggingface.co/sylvester-francis
+
+## Version History
+
+- **v1.0.0** (2025-11-29): Initial release
+  - Full merged model with LoRA adapters
+  - GGUF quantizations (q4_k_m, q6_k, f16)
+  - Ollama Modelfiles
+  - Optimized for React, Next.js, Angular, Node.js
+
+---
+
+**Keywords**: typescript, react, nextjs, angular, nodejs, code-generation, llm, gguf, ollama, qwen, lora, small-language-model