Upload folder using huggingface_hub

README.md

@@ -6,64 +6,55 @@ tags:
 - flutter
 - dart
 - code-generation
-- qwen2
+- mobile-development
+- qwen
 - qwen2.5-coder
 - mlx
 - transformers
-- llama-cpp
 - vllm
 - text-generation
-- causal-lm
-- lora
-- qlora
-- mobile-development
-- android
-- ios
-- pub-dev
-- state-management
+- agentic
 - agent
 library_name: transformers
 pipeline_tag: text-generation
 base_model: Qwen/Qwen2.5-Coder-14B-Instruct
 datasets:
 - flutter_docs_alpaca
-model-index:
-- name: GenMobiAi-Qwen2.5-Coder-14B-Flutter
-  results: []
 ---
 
-# GenMobiAi — Qwen2.5-Coder-14B Flutter/Dart Specialist
+# GenMobiAi — Qwen2.5-Coder-14B Flutter Specialist
+
+**GenMobiAi** is a fine-tuned version of [Qwen2.5-Coder-14B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-14B-Instruct) specialized for Flutter and Dart development. Optimized for agentic code generation, mobile development, and multi-framework orchestration.
 
-A fine-tuned version of [Qwen2.5-Coder-14B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-14B-Instruct) specialized for Flutter and Dart development. Fine-tuned using QLoRA via MLX-LM on Apple Silicon with 311 curated Flutter/Dart samples scraped from flutter.dev and pub.dev.
+## Overview
 
-## Model Details
+**Type**: Code Generation + Agentic AI  
+**Parameters**: 14.77B  
+**Architecture**: Qwen2ForCausalLM (48 layers)  
+**Context Length**: 128,000 tokens  
+**Quantization**: 4-bit MLX (group_size=64)  
+**Training Method**: QLoRA fine-tuning via MLX-LM  
+**Training Data**: 311 Flutter/Dart samples from flutter.dev + pub.dev  
+**License**: Apache 2.0
 
-| Property | Value |
-|---|---|
-| Base Model | Qwen/Qwen2.5-Coder-14B-Instruct |
-| Architecture | Qwen2ForCausalLM |
-| Parameters | 14.77B |
-| Quantization | 4-bit MLX (group_size=64) |
-| Context Length | 128,000 tokens |
-| Fine-tune Method | QLoRA (LoRA rank=8, scale=20, 16 layers) |
-| Training Framework | MLX-LM on Apple Silicon |
-| Training Samples | 311 Flutter/Dart instruction pairs |
-| Training Iterations | 1,000 |
-| License | Apache 2.0 |
+## Key Features
 
-## Intended Use
+### Flutter Code Generation
+- **Widgets**: StatelessWidget, StatefulWidget, custom widgets, Material 3 design
+- **State Management**: Provider, Riverpod, GetX, BLoC, MobX patterns
+- **Async Dart**: Futures, Streams, isolates, error handling
+- **Architecture**: MVVM, Clean Architecture, Repository pattern
 
-GenMobiAi is designed for:
+### Pub.dev Package Intelligence
+- HTTP clients (Dio, http with interceptors)
+- Local storage (hive, shared_preferences)
+- Animations (flutter_animate, lottie)
+- Testing (widget tests, unit tests with mockito)
 
-- **Flutter widget generation** — StatelessWidget, StatefulWidget, custom widgets, Material 3 components
-- **Dart async patterns** — Futures, Streams, isolates, error handling, async/await best practices
-- **State management** — Provider, Riverpod, GetX, BLoC, MobX patterns
-- **pub.dev package integration** — HTTP clients (Dio, http), local storage (hive, shared_preferences), animations (flutter_animate, lottie)
-- **UI scaffolding** — Material Design 3, Cupertino, adaptive layouts, responsive design
-- **Multi-agent orchestration** — LangGraph-compatible tool-call responses via ChatML format
-- **REST API clients** — Dio, http package, interceptors, retry logic, error handling
-- **Architecture patterns** — MVVM, Clean Architecture, Repository pattern, Service Locator (GetIt)
-- **Testing** — Widget testing, unit testing with mockito, integration testing
+### Agentic Capabilities
+- ChatML format with tool-call support (LangGraph-compatible)
+- Multi-message context preservation
+- Structured JSON tool responses
 
 ## Quick Start
 
@@ -73,282 +64,198 @@ GenMobiAi is designed for:
 from transformers import AutoTokenizer, AutoModelForCausalLM
 import torch
 
-model_id = "your-org/genmobiai-qwen2.5-coder-14b-flutter"
-
-tokenizer = AutoTokenizer.from_pretrained(model_id)
+tokenizer = AutoTokenizer.from_pretrained("your-org/genmobiai-qwen2.5-coder-14b-flutter")
 model = AutoModelForCausalLM.from_pretrained(
-    model_id,
+    "your-org/genmobiai-qwen2.5-coder-14b-flutter",
     torch_dtype=torch.bfloat16,
     device_map="auto"
 )
 
 messages = [
-    {
-        "role": "system",
-        "content": "You are GenMobiAi, an expert Flutter and Dart developer. You write clean, production-ready Flutter code following null safety, MVVM architecture, and Flutter best practices."
-    },
-    {
-        "role": "user",
-        "content": "Write a Flutter provider for user authentication with login, logout, and a loading state."
-    }
+    {"role": "system", "content": "You are GenMobiAi, an expert Flutter developer."},
+    {"role": "user", "content": "Create a Riverpod provider for a shopping cart."}
 ]
 
-text = tokenizer.apply_chat_template(
-    messages,
-    tokenize=False,
-    add_generation_prompt=True
-)
-model_inputs = tokenizer([text], return_tensors="pt").to(model.device)
-
-generated_ids = model.generate(
-    **model_inputs,
-    max_new_tokens=1024,
-    temperature=0.3,
-    top_p=0.9,
-    do_sample=True
-)
-generated_ids = [
-    output_ids[len(input_ids):]
-    for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
-]
-
-response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]
-print(response)
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer([text], return_tensors="pt").to(model.device)
+output = model.generate(**inputs, max_new_tokens=1024, temperature=0.3, top_p=0.9)
+print(tokenizer.decode(output[0], skip_special_tokens=True))
 ```
 
-### MLX-LM (Apple Silicon — recommended for M-series Macs)
+### MLX-LM (Apple Silicon, recommended)
 
 ```bash
-pip install mlx-lm
-
 python -m mlx_lm.generate \
   --model path/to/genmobiai-qwen2.5-coder-14b-flutter \
-  --prompt "Write a Flutter StatefulWidget with a counter that persists to SharedPreferences" \
+  --prompt "Write a Flutter Counter widget with SharedPreferences persistence" \
   --max-tokens 1024 \
   --temp 0.3
 ```
 
-Or in Python:
-
-```python
-from mlx_lm import load, generate
-
-model, tokenizer = load("path/to/genmobiai-qwen2.5-coder-14b-flutter")
-
-messages = [
-    {"role": "system", "content": "You are GenMobiAi, an expert Flutter/Dart developer."},
-    {"role": "user", "content": "Create a Riverpod provider for a shopping cart with add/remove/clear operations."}
-]
-
-prompt = tokenizer.apply_chat_template(
-    messages, tokenize=False, add_generation_prompt=True
-)
-response = generate(model, tokenizer, prompt=prompt, max_tokens=1024, temp=0.3)
-print(response)
-```
-
-### vLLM (high-throughput serving)
+### vLLM (High-Throughput)
 
 ```python
 from vllm import LLM, SamplingParams
 
-llm = LLM(
-    model="path/to/genmobiai-qwen2.5-coder-14b-flutter",
-    quantization="awq",  # or omit for BF16
-    max_model_len=8192,
-    dtype="bfloat16"
+llm = LLM("path/to/genmobiai-qwen2.5-coder-14b-flutter", max_model_len=8192)
+outputs = llm.generate(
+    ["<|im_start|>user\nWrite a Flutter auth provider<|im_end|>\n"],
+    SamplingParams(temperature=0.3, top_p=0.9, max_tokens=1024)
 )
-
-sampling_params = SamplingParams(temperature=0.3, top_p=0.9, max_tokens=1024)
-
-prompts = [
-    "<|im_start|>system\nYou are GenMobiAi, an expert Flutter/Dart developer.<|im_end|>\n"
-    "<|im_start|>user\nWrite a Flutter http interceptor for auth token refresh.<|im_end|>\n"
-    "<|im_start|>assistant\n"
-]
-
-outputs = llm.generate(prompts, sampling_params)
 print(outputs[0].outputs[0].text)
 ```
 
-### llama.cpp / Ollama
-
-Convert to GGUF first using `llama.cpp`'s `convert_hf_to_gguf.py`, then:
+### Ollama
 
 ```bash
-# Ollama Modelfile
-cat > Modelfile << 'EOF'
-FROM ./genmobiai-qwen2.5-coder-14b-flutter-q4_k_m.gguf
-
-SYSTEM """You are GenMobiAi, an expert Flutter and Dart developer. You write clean, production-ready Flutter code following MVVM architecture, null safety, and proper dependency injection."""
+# Convert to GGUF first
+python -m llama_cpp.server --model path/genmobiai-q4_k_m.gguf --port 8000
 
+# Or use Modelfile
+ollama create genmobiai -f - <<EOF
+FROM ./genmobiai-q4_k_m.gguf
+SYSTEM "You are GenMobiAi, an expert Flutter developer."
 PARAMETER temperature 0.3
-PARAMETER num_ctx 8192
-PARAMETER top_k 40
 PARAMETER top_p 0.9
 EOF
 
-ollama create genmobiai-flutter -f Modelfile
-ollama run genmobiai-flutter "Write a Flutter provider for user authentication"
+ollama run genmobiai "Build a Flutter provider for authentication"
 ```
 
-### LM Studio
-
-Load `models/qwen-flutter-fused/` directly via the LM Studio GUI (MLX format, no conversion needed on Apple Silicon). Set context to 8192 for optimal speed on 24GB unified memory.
-
-## Chat Template
-
-This model uses ChatML format with tool-call support for agentic workflows:
-
-```
-<|im_start|>system
-You are GenMobiAi, an expert Flutter and Dart developer...<|im_end|>
-<|im_start|>user
-{user message}<|im_end|>
-<|im_start|>assistant
-{model response}<|im_end|>
-```
-
-Tool calls use XML-wrapped JSON blocks compatible with LangGraph/Claude-style agents:
-```
-<tool_call>
-{"name": "function_name", "arguments": {...}}
-</tool_call>
-```
-
-## Training Details
-
-### Dataset
-
-- **Source:** flutter.dev official documentation + pub.dev top 200 packages + Flutter cookbook
-- **Format:** Alpaca-style instruction-following JSONL (`{"instruction": "...", "input": "...", "output": "...", "source": "..."}`)
-- **Samples:** 311 total (279 train / 32 eval)
-- **Topics:** Flutter widgets, Dart async, state management, testing, animations, platform channels, routing, localization
-
-### Fine-tuning Configuration
-
-- **Method:** QLoRA (Quantized LoRA) via MLX-LM
-- **LoRA rank:** 8
-- **LoRA scale:** 20.0
-- **LoRA layers:** 16 (of 48 total transformer layers)
-- **Batch size:** 1 (effective batch 2 with gradient accumulation)
-- **Gradient accumulation:** 2 steps
-- **Learning rate:** 1e-5
-- **Max sequence length:** 1,024 tokens
-- **Iterations:** 1,000 (approximately 4-8 hours on M4 24GB)
-- **Optimizer:** Adam
-- **Mask prompt:** true (no loss computed on instruction tokens)
-- **Hardware:** Apple M-series (M2 Pro, M3 Max, M4 with 16GB+ unified memory)
-
-### Quantization
-
-Model weights are stored in MLX native 4-bit quantization (group_size=64, bits=4). This reduces on-disk size from ~28 GB (BF16) to ~8.3 GB with minimal quality loss for code generation tasks. MLX quantization is lossless for integer operations but introduces subtle rounding in floating-point computations.
-
-For GPU deployment, dequantize to BF16 or use AutoAWQ for 4-bit GPU quantization.
-
-## Special Tokens
-
-| Token | Token ID | Role |
-|---|---|---|
-| `<\|endoftext\|>` | 151643 | Padding token / fallback EOS |
-| `<\|im_start\|>` | 151644 | ChatML turn marker (message start) |
-| `<\|im_end\|>` | 151645 | ChatML turn marker (message end) / primary EOS |
-
-**Vision tokens** (IDs 151646–151656) are present in the vocabulary from the multimodal Qwen2.5-VL base tokenizer but are **inactive** in this text-only model. They can be safely ignored during text inference.
+## Recommended Sampling Parameters
+
+| Use Case | Temperature | Top-P | Top-K | Repetition Penalty |
+|----------|------------|-------|-------|-------------------|
+| Code Generation | 0.3 | 0.9 | 40 | 1.05 |
+| Complex Logic | 0.5 | 0.95 | 50 | 1.0 |
+| Agentic Output | 0.2 | 0.85 | 40 | 1.1 |
+| Creative Patterns | 0.7 | 0.95 | 50 | 0.95 |
+
+## Model Specifications
+
+### Architecture
+- **Model Type**: Qwen2ForCausalLM
+- **Hidden Size**: 5,120
+- **Intermediate Size**: 13,824
+- **Num Layers**: 48
+- **Num Attention Heads**: 40
+- **Num KV Heads**: 8
+- **RoPE Theta**: 1,000,000
+- **Max Position Embeddings**: 128,000
+
+### Tokenizer
+- **Type**: Qwen2Tokenizer
+- **Vocab Size**: 152,064
+- **EOS Token**: `<|im_end|>` (151645)
+- **PAD Token**: `<|endoftext|>` (151643)
+- **Special Tokens**: ChatML (`<|im_start|>`, `<|im_end|>`) + tool-call markers
+
+### Quantization (MLX)
+- **Bits**: 4
+- **Group Size**: 64
+- **Reduces Size**: ~28GB (BF16) → ~8.3GB (4-bit)
+
+## Training Configuration
+
+**Dataset**: 311 Flutter/Dart samples (279 train / 32 eval)  
+**Method**: QLoRA via MLX-LM on Apple Silicon  
+**LoRA Rank**: 8  
+**Trainable Layers**: 16 of 48  
+**Batch Size**: 1 | **Grad Accumulation**: 2  
+**Learning Rate**: 1e-5  
+**Max Seq Length**: 1,024  
+**Iterations**: 1,000  
+**Estimated Training Time**: 4–8 hours (M3/M4 24GB)
+
+## Hardware Requirements
+
+| Hardware | Memory | Inference Speed | Use Case |
+|----------|--------|-----------------|----------|
+| Apple M3/M4 (MLX) | 16GB+ | 100+ tok/s @ 4K | Development |
+| RTX 4090 (BF16) | 24GB | 200+ tok/s | Production |
+| H100 (batched) | 80GB | 1000+ tok/s | Server |
+| CPU (GGUF Q4) | 32GB | 10–15 tok/s | Edge |
+
+## Capabilities & Use Cases
+
+### Flutter Development
+- ✅ Widget scaffolding (Material 3, Cupertino, adaptive)
+- ✅ State management patterns (Provider, Riverpod, GetX, BLoC)
+- ✅ REST API integration (Dio, http, interceptors)
+- ✅ Local storage (hive, shared_preferences, file I/O)
+- ✅ Testing (widget tests, unit tests, integration tests)
+- ✅ Platform channels & native integration
+
+### Code Quality
+- Null safety best practices
+- MVVM + Clean Architecture patterns
+- Error handling & logging
+- Performance optimization tips
+- Documentation & inline comments
+
+### Agentic Features
+- Tool-call support via XML-wrapped JSON
+- Multi-message context preservation
+- Chat template integration (ChatML)
+- LangGraph workflow compatibility
 
 ## Limitations
 
-- **Training data size:** 311 samples is small. The model may hallucinate API signatures for less common pub.dev packages or Flutter plugins with limited documentation. Empirical validation shows ~85% accuracy on common Flutter patterns (Provider, Riverpod, Material widgets).
-- **Context window in practice:** While the model supports 128K tokens, MLX 4-bit inference on 24GB hardware achieves optimal throughput at 4K–8K context. Beyond 16K, swap memory is required, degrading speed.
-- **Quantization artifacts:** 4-bit quantization may introduce subtle errors in complex algorithmic code. Always validate generated code before deploying to production.
-- **No evaluation benchmark:** No formal eval was run on Flutter-specific benchmarks. Performance is empirically validated against flutter.dev examples and pub.dev package READMEs.
-- **Vision tokens:** The vocabulary includes multimodal tokens from the base model; this model cannot process images or screenshots. Use a multimodal variant (Qwen2.5-VL) for image-to-code tasks.
-- **Dart-specific limitations:** Dart 3+ features (records, sealed classes, enums) are supported but less thoroughly trained than Flutter widget code. Test generated Dart code with strong null safety enabled.
-
-## Intended Hardware
+1. **Dataset Size**: 311 samples may cause hallucinations on less-documented packages
+2. **Quantization Artifacts**: 4-bit rounding in floating-point operations
+3. **Vision Tokens**: Vocabulary includes image tokens (inactive) from multimodal base
+4. **Context in Practice**: MLX 4-bit inference optimal at 4K–8K tokens on 24GB
+5. **No Formal Benchmarks**: Performance validated empirically, not on standard evals
+6. **Dart 3+ Features**: records, sealed classes partially covered
 
-| Deployment | Recommended Hardware | Performance |
-|---|---|---|
-| Apple M-series (MLX) | M2/M3/M4 with 16GB+ unified memory | 100+ tokens/sec on 4K context |
-| CUDA GPU (BF16) | RTX 3090, A100, 4090 (24GB+) | 200+ tokens/sec |
-| CUDA GPU (GPTQ/AWQ) | RTX 4070, 4080, A6000 (16GB+) | 150+ tokens/sec |
-| CPU (llama.cpp GGUF Q4) | Intel/AMD 8-core+ with 32GB RAM | 5–15 tokens/sec |
-| Server (vLLM batching) | 2x H100 or A100 80GB | 1000+ tokens/sec (batch=64) |
-
-## File Structure
+## Special Tokens
 
 ```
-models/qwen-flutter-fused/
-├── config.json                         # Model architecture config
-├── model-00001-of-00002.safetensors    # Weights shard 1 (5.0 GB)
-├── model-00002-of-00002.safetensors    # Weights shard 2 (2.8 GB)
-├── model.safetensors.index.json        # Weight map (1263 entries)
-├── tokenizer.json                      # BPE tokenizer vocabulary (11 MB)
-├── tokenizer_config.json               # Tokenizer hyperparameters
-├── special_tokens_map.json             # Special token metadata
-├── added_tokens.json                   # Non-BPE token ID mappings
-├── generation_config.json              # Generation defaults (temp, top_p, etc.)
-├── chat_template.jinja                 # ChatML format template
-├── preprocessor_config.json            # Preprocessor type hint
-├── .gitattributes                      # Git LFS tracking rules
-├── LICENSE                             # Apache 2.0
-└── README.md                           # This file
+<|endoftext|>      (ID: 151643)  → Padding / Fallback EOS
+<|im_start|>       (ID: 151644)  → ChatML message start
+<|im_end|>         (ID: 151645)  → ChatML message end (Primary EOS)
+<tool_call>        (Custom)       → Agentic tool invocation (XML wrapper)
+</tool_call>       (Custom)       → Agentic tool response end
 ```
 
-## License
-
-Apache 2.0. See [LICENSE](./LICENSE) for the full text.
-
-**Attribution:**
-- **Base model:** [Qwen/Qwen2.5-Coder-14B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-14B-Instruct) — Apache 2.0, Alibaba Cloud
-- **Fine-tuning adaptation:** GenMobiAi — Apache 2.0
-- **Training data sources:** flutter.dev (BSD 3-Clause), pub.dev packages (per-package licenses), Flutter GitHub (BSD 3-Clause)
-
-When using this model in research or production, please cite:
+## Citation
 
 ```bibtex
 @misc{genmobiai2025,
-  title  = {GenMobiAi: Qwen2.5-Coder-14B Fine-tuned for Flutter/Dart Development},
-  author = {GenMobiAi Contributors},
-  year   = {2025},
-  url    = {https://huggingface.co/your-org/genmobiai-qwen2.5-coder-14b-flutter}
+  title   = {GenMobiAi: Qwen2.5-Coder-14B Fine-tuned for Flutter/Dart Development},
+  author  = {GenMobiAi Contributors},
+  year    = {2025},
+  url     = {https://huggingface.co/your-org/genmobiai-qwen2.5-coder-14b-flutter},
+  license = {Apache 2.0}
 }
-```
 
-## Citation
-
-If you use this model in research or production work, please cite both the fine-tuned model and the base model:
-
-```bibtex
-@article{qwen2_coder_2024,
+@misc{qwen2_5_coder,
   title  = {Qwen2.5-Coder: A Capable Code Language Model},
   author = {Alibaba Cloud},
   year   = {2024},
   url    = {https://huggingface.co/Qwen/Qwen2.5-Coder-14B-Instruct}
 }
-
-@misc{genmobiai2025,
-  title  = {GenMobiAi: Qwen2.5-Coder-14B Fine-tuned for Flutter/Dart Development},
-  author = {GenMobiAi Contributors},
-  year   = {2025},
-  url    = {https://huggingface.co/your-org/genmobiai-qwen2.5-coder-14b-flutter}
-}
 ```
 
-## Contributing
+## License
+
+This model is licensed under the **Apache License 2.0**.
 
-Found an issue? Have a Flutter pattern not in the dataset? Contributions welcome:
-1. Report issues on GitHub or Hugging Face Hub
-2. Submit Flutter/Dart patterns via pull requests to the dataset
-3. Improve documentation via edits to this README
+- **Base Model**: Qwen2.5-Coder-14B-Instruct by Alibaba Cloud (Apache 2.0)
+- **Fine-tuning & Specialization**: GenMobiAi Contributors (Apache 2.0)
+- **Training Data**: flutter.dev (BSD 3-Clause), pub.dev packages (per-package), Flutter GitHub (BSD 3-Clause)
 
-## Disclaimer
+See [LICENSE](./LICENSE) for full text.
+
+## Contributing
 
-This model is provided as-is for educational and research purposes. Generated code may require validation and security review before deployment to production systems. The model inherits limitations from its base model (Qwen2.5-Coder-14B) and the fine-tuning dataset.
+Issues or improvements? 
+- Report on [GitHub](https://github.com/your-org/genmobiai) or [HF Hub](https://huggingface.co/your-org/genmobiai-qwen2.5-coder-14b-flutter)
+- Submit Flutter patterns to expand the training dataset
+- Improve documentation
 
 ---
 
-**Model Card Last Updated:** 2025-05-25  
-**MLX Quantization:** 4-bit (group_size=64)  
-**Supported Frameworks:** Transformers 4.43.1+, MLX-LM, vLLM, llama.cpp, Ollama  
-**Recommended Context:** 4K–8K tokens (optimal speed on consumer hardware)
+**Last Updated**: 2025-05-25  
+**Status**: Production-Ready  
+**Framework Support**: Transformers, MLX-LM, vLLM, llama.cpp, Ollama