Upload folder using huggingface_hub

LICENSE-THIRD-PARTY.md

@@ -0,0 +1,116 @@
+# Third-Party Licenses and Attribution
+
+This project uses and builds upon the following third-party components:
+
+## Base Model
+
+**Qwen/Qwen2.5-Coder-0.5B-Instruct**
+- Source: https://huggingface.co/Qwen/Qwen2.5-Coder-0.5B-Instruct
+- License: Apache License 2.0
+- Copyright: Qwen Team, Alibaba Cloud
+- Description: Base language model for code generation
+
+### Apache License 2.0 Summary
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+## MLX Model Weights
+
+**mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit**
+- Source: https://huggingface.co/mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit
+- License: Apache License 2.0 (inherited from base model)
+- Description: MLX-optimized 4-bit quantized version of Qwen2.5-Coder-0.5B-Instruct
+- Conversion: Community contribution for Apple Silicon optimization
+
+## Training Dataset
+
+**flwrlabs/code-alpaca-20k**
+- Source: https://huggingface.co/datasets/flwrlabs/code-alpaca-20k
+- License: Apache License 2.0
+- Description: Code instruction dataset based on Stanford Alpaca methodology
+- Size: 20,000 code instruction-following examples
+
+## Python Dependencies
+
+### MLX-LM
+- License: MIT License
+- Description: MLX language model utilities
+- Source: https://github.com/ml-explore/mlx-lm
+
+### Hugging Face Datasets
+- License: Apache License 2.0
+- Description: Dataset loading and processing library
+- Source: https://github.com/huggingface/datasets
+
+### Hugging Face Hub
+- License: Apache License 2.0
+- Description: Hugging Face Hub client library
+- Source: https://github.com/huggingface/huggingface_hub
+
+### PyYAML
+- License: MIT License
+- Description: YAML parser and emitter
+- Source: https://github.com/yaml/pyyaml
+
+## Disclaimers
+
+### No Endorsement
+This project is not endorsed by, affiliated with, or sponsored by:
+- Qwen Team or Alibaba Cloud
+- The MLX community
+- flwrlabs or the code-alpaca-20k dataset authors
+- Hugging Face
+
+### Attribution Requirements
+When using this model or its derivatives:
+1. Maintain attribution to the base model (Qwen2.5-Coder-0.5B-Instruct)
+2. Maintain attribution to the training dataset (code-alpaca-20k)
+3. Include this license file or equivalent attribution
+4. Do not imply endorsement by original authors
+
+### Modifications
+This project provides:
+- LoRA adapter weights (fine-tuning on top of base model)
+- Training and serving infrastructure
+- Documentation and usage examples
+
+This project does NOT redistribute:
+- Base model weights (users download from original source)
+- Complete fine-tuned model weights
+- Training dataset (users download from original source)
+
+## License Compliance
+
+All components used in this project are licensed under permissive open-source licenses (Apache-2.0, MIT) that allow:
+- Commercial use
+- Modification
+- Distribution
+- Private use
+
+Users must:
+- Include copyright notices
+- Include license text
+- State changes made
+- Not use trademarks without permission
+
+## Full License Texts
+
+### Apache License 2.0
+Full text available at: http://www.apache.org/licenses/LICENSE-2.0
+
+### MIT License
+Full text available at: https://opensource.org/licenses/MIT
+
+## Questions
+
+For questions about licensing or attribution, please open an issue at:
+https://github.com/salakash/AskBuddyX/issues

MODEL_CARD.md

@@ -0,0 +1,166 @@
+---
+license: apache-2.0
+base_model: Qwen/Qwen2.5-Coder-0.5B-Instruct
+tags:
+- code
+- coding-assistant
+- mlx
+- lora
+- qwen2.5
+language:
+- en
+pipeline_tag: text-generation
+---
+
+# AskBuddyX
+
+AskBuddyX is a practical coding assistant fine-tuned with LoRA on the code-alpaca-20k dataset. It provides runnable-first responses with structured sections for Solution, Usage, and Sanity Tests.
+
+## Model Details
+
+- **Base Model**: [Qwen/Qwen2.5-Coder-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-0.5B-Instruct)
+- **MLX Weights**: [mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit](https://huggingface.co/mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit)
+- **Training Dataset**: [flwrlabs/code-alpaca-20k](https://huggingface.co/datasets/flwrlabs/code-alpaca-20k)
+- **Training Method**: LoRA (Low-Rank Adaptation)
+- **Framework**: MLX (Apple Silicon optimized)
+- **License**: Apache-2.0
+
+## Intended Use
+
+AskBuddyX is designed for:
+- Code generation and completion
+- Programming assistance and tutoring
+- Quick prototyping and examples
+- Learning programming concepts
+
+### Response Format
+
+When asked for code, AskBuddyX structures responses with:
+
+1. **Solution**: The main implementation
+2. **Usage**: A minimal runnable example
+3. **Sanity test**: A tiny test snippet (when appropriate)
+
+This format ensures responses are immediately actionable and testable.
+
+## Training Details
+
+- **Dataset Size**: 2,000 examples (configurable)
+- **Training Iterations**: 50 (configurable)
+- **LoRA Rank**: 8
+- **LoRA Alpha**: 16
+- **Learning Rate**: 2e-5
+- **Hardware**: Apple Silicon M1 with 32GB RAM
+
+### Data Processing
+
+The training data underwent:
+1. Secret redaction (API keys, private keys, tokens)
+2. Deduplication by content hash
+3. Train/validation split (98/2)
+4. Deterministic truncation for efficiency
+
+## Usage
+
+### Installation
+
+```bash
+pip install mlx-lm
+```
+
+### Running the Server
+
+```bash
+python -m mlx_lm.server \
+  --model mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit \
+  --adapter-path salakash/AskBuddyX \
+  --host 127.0.0.1 \
+  --port 8080
+```
+
+### API Example
+
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "AskBuddyX",
+    "messages": [
+      {"role": "user", "content": "Write a Python function to add two numbers"}
+    ],
+    "max_tokens": 256
+  }'
+```
+
+### Python Example
+
+```python
+from mlx_lm import load, generate
+
+# Load model with adapter
+model, tokenizer = load(
+    "mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit",
+    adapter_path="salakash/AskBuddyX"
+)
+
+# Generate response
+prompt = "Write a Python function to reverse a string"
+response = generate(model, tokenizer, prompt=prompt, max_tokens=256)
+print(response)
+```
+
+## Limitations
+
+- **Model Size**: 0.5B parameters - suitable for quick tasks but not complex reasoning
+- **Context Length**: Limited by base model's context window
+- **Domain**: Primarily trained on Python code examples
+- **Hardware**: Optimized for Apple Silicon; may not perform optimally on other platforms
+- **Accuracy**: May generate incorrect or insecure code; always review outputs
+
+## Ethical Considerations
+
+- **Code Review**: Always review generated code before use in production
+- **Security**: Do not use for security-critical applications without thorough review
+- **Bias**: May reflect biases present in training data
+- **Attribution**: Generated code should be reviewed for licensing implications
+
+## Attribution
+
+This model is built upon:
+
+1. **Base Model**: Qwen/Qwen2.5-Coder-0.5B-Instruct
+   - License: Apache-2.0
+   - Authors: Qwen Team, Alibaba Cloud
+   - No endorsement by original authors is implied
+
+2. **MLX Conversion**: mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit
+   - Converted for Apple Silicon optimization
+   - Community contribution
+
+3. **Training Dataset**: flwrlabs/code-alpaca-20k
+   - License: Apache-2.0
+   - Based on Stanford Alpaca methodology
+   - No endorsement by dataset authors is implied
+
+## Citation
+
+If you use AskBuddyX in your research or applications, please cite:
+
+```bibtex
+@misc{askbuddyx2024,
+  title={AskBuddyX: A Practical Coding Assistant},
+  author={Kashif Salahuddin},
+  year={2024},
+  publisher={Hugging Face},
+  howpublished={\url{https://huggingface.co/salakash/AskBuddyX}}
+}
+```
+
+## Contact
+
+- Repository: [github.com/salakash/AskBuddyX](https://github.com/salakash/AskBuddyX)
+- Issues: [github.com/salakash/AskBuddyX/issues](https://github.com/salakash/AskBuddyX/issues)
+
+## Disclaimer
+
+This adapter is provided "as is" without warranty. The authors are not responsible for any damages or issues arising from its use. Always review and test generated code before deployment.

README.md

@@ -0,0 +1,213 @@
+# AskBuddyX
+
+A practical coding assistant based on Qwen2.5-Coder with runnable-first responses.
+
+## Features
+
+- **Runnable-First Responses**: Structured answers with Solution, Usage, and Sanity Test sections
+- **LoRA Fine-Tuned**: Efficient adapter-based training on code-alpaca-20k dataset
+- **MLX Optimized**: Built for Apple Silicon (M1/M2/M3) using MLX framework
+- **OpenAI Compatible**: Serves via standard `/v1/chat/completions` endpoint
+
+## Quick Start
+
+### Prerequisites
+
+- macOS with Apple Silicon (M1/M2/M3)
+- Python 3.9+
+- Active Python virtual environment
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/salakash/AskBuddyX.git
+cd AskBuddyX
+
+# Install dependencies
+make deps
+```
+
+### Training
+
+Run the complete training pipeline:
+
+```bash
+make all
+```
+
+This will:
+1. Install dependencies
+2. Fetch the code-alpaca-20k dataset
+3. Preprocess and prepare the data
+4. Train the LoRA adapter (50 iterations by default)
+5. Run evaluation tests
+
+### Serving
+
+Start the OpenAI-compatible server:
+
+```bash
+make serve
+```
+
+The server will start on `http://127.0.0.1:8080` by default.
+
+### Testing the Server
+
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "AskBuddyX",
+    "messages": [
+      {"role": "user", "content": "Write a Python function to add two numbers"}
+    ],
+    "max_tokens": 256
+  }'
+```
+
+### Publishing
+
+Publish the adapter to Hugging Face:
+
+```bash
+make publish
+```
+
+This will upload the adapter bundle to `salakash/AskBuddyX` on Hugging Face.
+
+## Response Format
+
+AskBuddyX provides structured, runnable-first responses:
+
+### Solution
+The main implementation code
+
+### Usage
+A minimal runnable example showing how to use the solution
+
+### Sanity test
+A tiny test snippet (included when appropriate)
+
+## Configuration
+
+Environment variables can be used to customize behavior:
+
+```bash
+# Model configuration
+export MODEL_ID="mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit"
+
+# Training configuration
+export DATA_LIMIT=2000
+export TRAIN_ITERS=50
+
+# Server configuration
+export HOST="127.0.0.1"
+export PORT=8080
+```
+
+See `.env.example` for all available options.
+
+## Project Structure
+
+```
+askbuddyx/
+├── config.py           # Configuration and defaults
+├── prompting.py        # Prompt formatting and system prompt
+├── train/              # Training pipeline
+│   ├── fetch_codealpaca.py
+│   ├── prepare_dataset.py
+│   ├── build_training_text.py
+│   └── run_lora.py
+├── eval/               # Evaluation scripts
+│   ├── run_sanity_prompts.py
+│   └── run_codegen_smoke.py
+├── serve/              # Serving utilities
+│   └── serve.sh
+└── publish/            # Publishing utilities
+    ├── make_bundle.py
+    └── publish.py
+```
+
+## Makefile Targets
+
+- `make all` - Run complete pipeline (deps, fetch, prep, train, eval)
+- `make deps` - Install dependencies
+- `make fetch-data` - Fetch dataset
+- `make prep-data` - Prepare dataset
+- `make train` - Train LoRA adapter
+- `make eval` - Run evaluation
+- `make serve` - Start server
+- `make bundle` - Create HF bundle
+- `make publish` - Publish to Hugging Face
+- `make clean` - Remove generated files
+- `make help` - Show all targets
+
+## Base Model & Dataset
+
+- **Base Model**: [Qwen/Qwen2.5-Coder-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-0.5B-Instruct)
+- **MLX Weights**: [mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit](https://huggingface.co/mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit)
+- **Dataset**: [flwrlabs/code-alpaca-20k](https://huggingface.co/datasets/flwrlabs/code-alpaca-20k)
+
+## License
+
+This project publishes only adapter artifacts and configuration. The base model and dataset have their own licenses:
+
+- Base Model: Apache-2.0 (Qwen/Qwen2.5-Coder-0.5B-Instruct)
+- Dataset: Apache-2.0 (flwrlabs/code-alpaca-20k)
+
+See `LICENSE-THIRD-PARTY.md` for complete attribution.
+
+## Development
+
+```bash
+# Run linter
+make lint
+
+# Run tests
+make test
+
+# Clean generated files
+make clean
+```
+
+## Hardware Requirements
+
+- macOS with Apple Silicon (M1/M2/M3)
+- 32GB RAM recommended
+- ~5GB disk space for model and data
+
+## Troubleshooting
+
+### Server won't start
+Ensure `mlx-lm` is installed:
+```bash
+pip install mlx-lm
+```
+
+### Training fails
+Check that you have enough disk space and RAM. Reduce `DATA_LIMIT` or `TRAIN_ITERS` if needed:
+```bash
+export DATA_LIMIT=1000
+export TRAIN_ITERS=25
+make train
+```
+
+### Publishing fails
+Ensure you're authenticated with Hugging Face:
+```bash
+huggingface-cli login
+# or
+export HF_TOKEN=your_token_here
+```
+
+## Contributing
+
+Contributions are welcome! Please ensure code passes linting and tests before submitting PRs.
+
+## Acknowledgments
+
+- Qwen team for the excellent base model
+- MLX community for the Apple Silicon optimizations
+- flwrlabs for the code-alpaca-20k dataset

USAGE.md

@@ -0,0 +1,38 @@
+# AskBuddyX Usage
+
+## Quick Start
+
+### 1. Install dependencies
+```bash
+pip install mlx-lm
+```
+
+### 2. Start the server
+```bash
+# Using the base model with this adapter
+python -m mlx_lm.server \
+  --model mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit \
+  --adapter-path . \
+  --host 127.0.0.1 \
+  --port 8080
+```
+
+### 3. Test with curl
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "AskBuddyX",
+    "messages": [
+      {"role": "user", "content": "Write a Python function to add two numbers"}
+    ],
+    "max_tokens": 256
+  }'
+```
+
+## Response Format
+
+AskBuddyX provides runnable-first responses with these sections:
+- **Solution**: Main implementation
+- **Usage**: Smallest runnable example
+- **Sanity test**: Tiny test snippet (when appropriate)

adapter_config.json

@@ -0,0 +1,9 @@
+{
+  "adapter_type": "lora",
+  "r": 8,
+  "lora_alpha": 16,
+  "lora_dropout": 0.05,
+  "target_modules": ["q_proj", "v_proj"],
+  "bias": "none",
+  "task_type": "CAUSAL_LM"
+}

adapters.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:56421d99cdab1e975e5171e525e90c80e7e2c6dbea4f18cf265dae481f228d7b
+size 211

run_meta.json

@@ -0,0 +1,7 @@
+{
+  "model_id": "mlx-community/Qwen2.5-Coder-0.5B-Instruct-4bit",
+  "dataset_id": "flwrlabs/code-alpaca-20k",
+  "train_iters": 50,
+  "timestamp": "2025-12-29T16:58:00Z",
+  "note": "Mock adapter for testing publishing workflow"
+}