README updated.

.gitignore

@@ -15,3 +15,10 @@ docs/assets/*.png
 docs/assets/*.jpg
 docs/assets/*.jpeg
 docs/assets/*.gif
+
+!fine_tuning/GGUF_CONVERSION.md
+!fine_tuning/README.md
+!fine_tuning/MODEL_CARD.md
+!fine_tuning/data/.gitkeep
+fine_tuning/data/**/*.jsonl
+fine_tuning/data/**/*.csv

README.md

@@ -21,6 +21,8 @@ Advisor is a local-first Google Ads analysis dashboard for small businesses. It
 
 The app combines live Google Ads data with sample demo data, then turns campaign metrics into clear recommendations through a fine-tuned GGUF model running with `llama.cpp`, plus rule-based logic for budget-sensitive decisions.
 
+**Fine-tuned model:** [ps1811/advisor-minicpm-finetuned-gguf](https://huggingface.co/ps1811/advisor-minicpm-finetuned-gguf/tree/main)
+
 ## Screenshots
 
 ![Dashboard](docs/assets/dashboard.png)
@@ -85,7 +87,7 @@ app.py
 
 Advisor uses a fine-tuned MiniCPM GGUF model hosted on Hugging Face:
 
-<https://huggingface.co/ps1811/advisor-minicpm-finetuned-gguf/tree/main>
+[ps1811/advisor-minicpm-finetuned-gguf](https://huggingface.co/ps1811/advisor-minicpm-finetuned-gguf/tree/main)
 
 The model is downloaded with `hf_hub_download` and loaded through `llama-cpp-python`.
 

fine_tuning/MODEL_CARD.md

@@ -0,0 +1,151 @@
+---
+language:
+  - en
+license: apache-2.0
+base_model: openbmb/MiniCPM5-1B
+tags:
+  - gguf
+  - llama-cpp
+  - qlora
+  - google-ads
+  - marketing-analytics
+  - local-ai
+  - small-business
+pipeline_tag: text-generation
+---
+
+# Advisor MiniCPM Fine-Tuned GGUF
+
+This model is a fine-tuned MiniCPM model for **Advisor**, a local-first Google Ads analysis app for small businesses. The model is designed to turn campaign, keyword, and search-term metrics into concise, actionable marketing recommendations.
+
+It is used in the Advisor app here:
+
+https://huggingface.co/spaces/build-small-hackathon/Advisor
+
+Project repository:
+
+https://github.com/PoornimaShridhar/Advisor
+
+## Intended Use
+
+The model is tuned for short Google Ads advisory outputs, especially:
+
+- campaign performance summaries
+- keyword inspection
+- search term cleanup
+- concise action bullets grounded in metrics
+- small-business-friendly explanations
+
+In the app, the LLM is used for explanation-heavy cards:
+
+- Ads Analyst
+- Keyword Inspector
+- Search Term Cleaner
+
+Budget-sensitive decisions are intentionally handled by deterministic rule-based logic in the app, not delegated fully to the model.
+
+## Fine-Tuning Summary
+
+The model was fine-tuned from:
+
+```text
+openbmb/MiniCPM5-1B
+```
+
+The training workflow used QLoRA with 4-bit loading, then merged the LoRA adapter into the base model before converting the merged model to GGUF for local inference.
+
+High-level process:
+
+1. Prepared instruction-style chat examples in JSONL format.
+2. Mixed synthetic Google Ads examples with cleaned campaign-style examples.
+3. Trained a LoRA adapter with `transformers`, `peft`, `trl`, and `bitsandbytes`.
+4. Merged the LoRA adapter into the base model.
+5. Converted the merged model to GGUF with `llama.cpp`.
+6. Quantized the GGUF model to `Q4_K_M`.
+7. Loaded the final model locally through `llama-cpp-python` in the Advisor app.
+
+## Training Data Format
+
+Each training record followed a chat-style JSONL structure:
+
+```json
+{
+  "messages": [
+    {
+      "role": "system",
+      "content": "You are a Google Ads analyst. Reply with concise actionable markdown bullets only."
+    },
+    {
+      "role": "user",
+      "content": "Analyze this Google Ads campaign data..."
+    },
+    {
+      "role": "assistant",
+      "content": "- Pause weak search terms with spend and no conversions.\n\n- Scale efficient keywords with conversions below target CPA."
+    }
+  ]
+}
+```
+
+The fine-tuning target was not general conversation. The goal was to teach the model to write short, grounded, metric-aware recommendations.
+
+## Training Configuration
+
+The project training script uses:
+
+```text
+Training method: QLoRA
+Max sequence length: 2048
+Epochs: 2
+Learning rate: 2e-4
+Batch size: 2
+Gradient accumulation: 8
+LoRA rank: 16
+LoRA alpha: 32
+LoRA dropout: 0.05
+Optimizer: paged_adamw_8bit
+Quantization during training: 4-bit NF4
+```
+
+LoRA target modules:
+
+```text
+q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
+```
+
+## Runtime
+
+The Advisor app downloads this GGUF model with `hf_hub_download` and runs it locally with `llama-cpp-python`.
+
+Default app configuration:
+
+```text
+LLAMA_HF_REPO=ps1811/advisor-minicpm-finetuned-gguf
+LLAMA_HF_FILENAME=advisor-minicpm-q4_k_m.gguf
+LLAMA_N_CTX=2048
+LLAMA_GPU_LAYERS=-1
+LLAMA_N_THREADS=4
+```
+
+## Example Output Style
+
+The expected output style is concise markdown bullets:
+
+```text
+- Treat "preschool near me" as a winning keyword because it produced conversions at an efficient CPA.
+
+- Reduce spend on broad, low-intent terms that generated clicks but no leads.
+
+- Add irrelevant search terms as negatives to protect budget for higher-intent traffic.
+```
+
+## Limitations
+
+- The model is specialized for Google Ads-style campaign analysis and may not perform well as a general assistant.
+- It should not be used as the only source of truth for financial decisions.
+- Budget changes in the Advisor app are handled by rule-based logic because spend decisions need predictable behavior.
+- Outputs should be reviewed by a human before applying recommendations to a live ad account.
+
+## Privacy
+
+The public repository does not include private Google Ads credentials or private training exports. Users running the app must provide their own Google Ads API credentials.

fine_tuning/README.md

@@ -0,0 +1,130 @@
+# Advisor Fine-Tuning Kit
+
+This folder is for preparing a small instruction-tuning dataset for the Advisor card outputs.
+
+Your app currently runs a GGUF model with `llama.cpp`. Do not fine-tune the `.gguf` file directly. Fine-tune the base Hugging Face model with LoRA or QLoRA, then convert the merged model back to GGUF for app deployment.
+
+## Recommended Split
+
+Keep deterministic logic for cards where the decision can be computed:
+
+- Budget Optimizer: rule-based decision engine
+- Growth Finder: rule-based decision engine
+
+Use the LLM where language synthesis still helps:
+
+- Ads Analyst
+- Keyword Inspector
+- Search Term Cleaner
+
+For Budget and Growth, optional fine-tuning examples should teach the model to rewrite already-computed decisions, not make the decision.
+
+## Dataset Size
+
+Start small and high quality:
+
+- Minimum useful: 200-300 examples
+- Good v1: 800-1,500 examples
+- Stronger v2: 3,000-5,000 examples
+
+Suggested v1 mix:
+
+- 250 Ads Analyst examples
+- 250 Keyword Inspector examples
+- 250 Search Term Cleaner examples
+- 150 Budget rewrite examples
+- 100 Growth rewrite examples
+
+## JSONL Format
+
+Each line is one chat example:
+
+```json
+{"messages":[{"role":"system","content":"You are a Google Ads analyst. Reply with concise actionable bullet points only."},{"role":"user","content":"Write 3 to 5 bullet points... Data (JSON): ..."},{"role":"assistant","content":"- Pause 'toy store near me' because it spent 586.50 across 184 clicks with 0 conversions.\n\n- Add 'preschool fees near me' as a keyword because it produced 21 conversions at CPA 10.40 and CVR 13.04%."}]}
+```
+
+Good assistant outputs must be:
+
+- 3 to 5 markdown bullets
+- Self-contained sentences
+- Specific about the campaign, keyword, or search term
+- Specific about the action
+- Grounded in metrics from the prompt
+- No intro sentence
+- No schema explanations
+- No thinking aloud
+- No quoted action fragments copied from JSON
+
+## Local Dataset Workflow
+
+From the Advisor repo root:
+
+```bash
+python fine_tuning/scripts/build_seed_dataset.py --out fine_tuning/data/seed.jsonl
+python fine_tuning/scripts/validate_jsonl.py fine_tuning/data/seed.jsonl
+```
+
+To build the 3-card training mix from the uncleaned Google Ads CSV plus synthetic examples:
+
+```bash
+python fine_tuning/scripts/build_csv_training_mix.py \
+  --csv C:/Users/ASUS/Downloads/GoogleAds_DataAnalytics_Sales_Uncleaned.csv \
+  --out_dir fine_tuning/data/csv_mix \
+  --csv_count 400 \
+  --synthetic_count 600
+
+python fine_tuning/scripts/validate_jsonl.py fine_tuning/data/csv_mix/train.jsonl
+python fine_tuning/scripts/validate_jsonl.py fine_tuning/data/csv_mix/val.jsonl
+```
+
+This creates:
+
+```text
+fine_tuning/data/csv_mix/csv_cleaned_pruned.csv
+fine_tuning/data/csv_mix/train.jsonl
+fine_tuning/data/csv_mix/val.jsonl
+```
+
+Then manually add curated real examples to:
+
+```text
+fine_tuning/data/manual.jsonl
+```
+
+Combine files however you prefer into:
+
+```text
+fine_tuning/data/train.jsonl
+fine_tuning/data/val.jsonl
+```
+
+## Training On A GPU Machine
+
+Install training dependencies from:
+
+```bash
+pip install -r fine_tuning/requirements-train.txt
+```
+
+Run QLoRA:
+
+```bash
+python fine_tuning/scripts/train_qlora.py \
+  --model_id openbmb/MiniCPM5-1B \
+  --train_file fine_tuning/data/train.jsonl \
+  --val_file fine_tuning/data/val.jsonl \
+  --output_dir fine_tuning/out/advisor-minicpm-lora
+```
+
+Confirm the non-GGUF base model ID before training. Your current inference model is:
+
+```text
+openbmb/MiniCPM5-1B-GGUF / MiniCPM5-1B-Q4_K_M.gguf
+```
+
+After LoRA training, merge the adapter into the base model, convert to GGUF with `llama.cpp`, quantize to `Q4_K_M`, upload to Hugging Face, then update:
+
+```python
+LLAMA_HF_REPO = "your-user/advisor-minicpm-finetuned-gguf"
+LLAMA_HF_FILENAME = "advisor-minicpm-q4_k_m.gguf"
+```