Upload 2 files

finetune/FINETUNE_GUIDE.md

@@ -0,0 +1,126 @@
+# 🎯 Well-Tuned — fine-tune & publish your own model (step by step)
+
+Goal: publish a small **fine-tuned** model on Hugging Face and use it inside the
+app. We fine-tune **Qwen3-1.7B** on one focused skill the app already performs —
+turning a Chan-theory *raw read* into a crisp long-hold *AI summary* — then plug
+it back in as the Translator sub-agent. This earns **🎯 Well-Tuned** and
+strengthens **🐜 Tiny Titan** (a 1.7B model doing the job well).
+
+Everything you need is already in the app and in this `finetune/` folder. Total
+hands-on time ≈ 1 hour, most of it waiting.
+
+---
+
+## Why this approach (read once)
+
+- **Self-sourcing data.** You don't hunt for a dataset — the app *generates* it.
+  Each time you run the Signals **AI summary**, the (raw read → narrative) pair
+  is saved to `/data/dataset/pairs.jsonl`. A few hundred pairs is plenty.
+- **Single skill, small model.** Narrowing the task lets 1.7B match or beat a
+  generic 4B, which is the whole point of the hackathon's "think small".
+- **Honest fit.** The fine-tune does exactly what the app uses it for — judges
+  can see the loop close.
+
+---
+
+## Step 1 — Capture training data (in the app, ~15 min)
+
+1. Open the Space → **Signals** → **Run analysis**.
+2. For each ticker: pick it in the dropdown, click **🤖 AI summary**. Each run
+   auto-saves one training pair (you'll see them counted on the Model tab).
+3. Vary it: change the ticker pool (large caps, a few volatile names, an ETF),
+   re-run analysis, summarize again. Aim for **150–500 pairs**.
+   - Tip: the **Auto Research** reports and the **rotation narrative** also
+     exercise the models, but only the Signals AI summary is captured for SFT
+     (it's the cleanest single-skill pair).
+4. **Model tab → 🎯 Fine-tuning dataset → ⬇ Export dataset (JSONL)**. It writes
+   `/data/dataset/chan_sft_<timestamp>.jsonl` and tells you the pair count.
+
+### Get the file onto your computer
+The file lives on the Space's `/data` bucket. Easiest way to grab it:
+```bash
+pip install huggingface_hub
+huggingface-cli login          # your token
+# list what's in the Space's persistent storage isn't exposed directly, so
+# instead download via the Space's file browser, OR re-export to the repo:
+```
+Simplest reliable path: in the **Model tab** the export prints the full path;
+open the Space's **Files** isn't enough for /data, so use the Space terminal if
+you enabled "Dev mode", **or** temporarily add a `gr.File` download — if you
+want that button, tell me and I'll wire it in. Otherwise the Colab notebook
+also accepts the JSONL via direct upload (Step 2 there).
+
+> If you'd rather not fish the file out of `/data`, I can add a one-click
+> **"Download dataset"** button to the Model tab — say the word.
+
+---
+
+## Step 2 — Train on a free Colab T4 (~25–40 min)
+
+1. Go to <https://colab.research.google.com> → **File → Upload notebook** →
+   pick `finetune/chan_finetune_colab.ipynb` from this project.
+2. **Runtime → Change runtime type → T4 GPU → Save.**
+3. Run the cells top to bottom:
+   - Cell 1 installs Unsloth (fast, low-memory LoRA).
+   - Cell 2 asks you to **upload your `chan_sft_*.jsonl`**.
+   - Cells 3–5 load Qwen3-1.7B in 4-bit, attach LoRA adapters, and train
+     (3 epochs; 10–20 min for a few hundred rows).
+   - Cell 6 prints a sample generation so you can eyeball quality.
+4. If the sample looks off, raise `num_train_epochs` to 4–5 and re-run Cell 5.
+
+---
+
+## Step 3 — Convert to GGUF + publish (~5 min, same notebook)
+
+1. Cell 7: `login()` — paste a **write** token (HF → Settings → Access Tokens).
+2. Set `HF_USER = 'ranranrunforit'`. The cell calls
+   `model.push_to_hub_gguf(REPO, tokenizer, quantization_method='q8_0')`, which
+   merges the LoRA, converts to GGUF via llama.cpp, and uploads to
+   `ranranrunforit/chan-compass-qwen3-1.7b-gguf`.
+3. Open the new repo → **Files** → note the exact `.gguf` filename (e.g.
+   `chan-compass-qwen3-1.7b-gguf.Q8_0.gguf` — Unsloth's name may differ).
+
+---
+
+## Step 4 — Wire it into the app (1 line, ~2 min)
+
+In `llm_local.py`, find the commented block in `MODEL_ZOO` and edit it to match
+your repo id and the **exact** filename from Step 3:
+
+```python
+"Chan-Tuned Qwen3-1.7B · my fine-tune": (
+    "ranranrunforit/chan-compass-qwen3-1.7b-gguf",
+    "chan-compass-qwen3-1.7b-gguf.Q8_0.gguf"),   # ← exact filename
+```
+
+Optionally make it the fast sub-agent's default so the app uses it everywhere:
+
+```python
+FAST_MODEL = "Chan-Tuned Qwen3-1.7B · my fine-tune"
+```
+
+Commit, reboot the Space. The Model tab now lists your fine-tune, and it loads
+through llama.cpp like any other GGUF. **🎯 Well-Tuned achieved.**
+
+---
+
+## Checklist for the badge
+
+- [ ] Dataset exported from the app (`chan_sft_*.jsonl`).
+- [ ] LoRA trained on Qwen3-1.7B (Colab T4).
+- [ ] Merged + converted to GGUF, **published to a public HF repo**.
+- [ ] App's `MODEL_ZOO` points at that repo; it loads and answers.
+- [ ] (Nice) Mention the fine-tune in your demo + blog (`BLOG_DRAFT.md`).
+
+## Troubleshooting
+
+- **Colab OOM on T4:** keep `load_in_4bit=True`, batch size 2, max_seq_length
+  2048 (defaults here). Don't bump LoRA `r` above 32.
+- **`push_to_hub_gguf` slow/fails:** re-run the cell; conversion downloads
+  llama.cpp once. If it still fails, save the merged model with
+  `model.save_pretrained_merged(...)` and convert locally with
+  `llama.cpp/convert_hf_to_gguf.py` (also documented in Unsloth's README).
+- **Model loads but talks oddly:** too few pairs or too many epochs. 200+ pairs,
+  3 epochs is the sweet spot. Keep temperature low (the app uses 0.2 here).
+- **Space can't find the file:** the filename in `MODEL_ZOO` must match the repo
+  exactly (case-sensitive), and the repo must be public (or set HF_TOKEN).