Upload docs/MAMBA_REASONING_FINETUNING_PLAN.md with huggingface_hub

docs/MAMBA_REASONING_FINETUNING_PLAN.md

@@ -0,0 +1,79 @@
+# Implementation Plan: Fine-Tuning Mamba 7B for Deep Chain-of-Thought Reasoning
+
+This project aims to fine-tune a 7-billion parameter State Space Model (**Mamba 7B**) to endow it with native **DeepSeek-R1 style Chain-of-Thought (`<think>`) internal reasoning capabilities**.
+
+Mamba's constant $O(1)$ memory state and $O(N)$ linear-time complexity make it exceptionally efficient. Infusing it with deep step-by-step CoT reasoning allows Mamba to perform complex mathematical logic, system architecture design, and algorithm derivation without suffering from Transformer KV-cache memory expansion.
+
+---
+
+## 🎯 Primary Goals
+
+1. **Dataset Pipeline**: Download and format a high-density DeepSeek-R1 distilled reasoning dataset ([`BespokeLabs/Bespoke-Stratos-17k`](https://huggingface.co/datasets/BespokeLabs/Bespoke-Stratos-17k) or [`open-thoughts/OpenThoughts-114k`](https://huggingface.co/datasets/open-thoughts/OpenThoughts-114k)) into standard multi-turn chat format with explicit `<think>...</think>` tags.
+2. **Multi-GPU SFT Fine-Tuning**: Execute fine-tuning of Mamba 7B (`tiiuae/falcon-mamba-7b-instruct` or `mistralai/mamba-codestral-7b`) on 2x NVIDIA H200 NVL GPUs (282 GB VRAM) utilizing PyTorch, `transformers`, and optimized `mamba-ssm` CUDA kernels.
+3. **Reasoning Benchmark Evaluation**: Evaluate the fine-tuned Mamba Reasoning model against the base Mamba 7B on 100 complex mathematical, logical, and software architecture benchmarks.
+4. **GGUF Export & Ollama Registration**: Convert merged weights to F16 GGUF and register in local Ollama as `mamba-7b-reasoning:latest`.
+5. **Hugging Face Publication**: Publish adapter weights, GGUF binary, Model Card, and benchmark report to Hugging Face (`namanadep/Mamba-7B-Reasoning`).
+
+---
+
+## 🏗️ Proposed Architecture & File Layout
+
+All code, scripts, configuration, and documentation will reside in `/home/adminuser/aiops_pocs/MAMBA_FINETUNING/` (symlinked as `/home/adminuser/MAMBA_FINETUNING/`). All datasets, heavy model weights, checkpoints, and GGUF binaries will reside under `/data/pocs_models_and_checkpoints/MAMBA_FINETUNING/`.
+
+### Directory Structure:
+```
+/home/adminuser/MAMBA_FINETUNING/
+├── docs/                                              # Documentation & Walkthroughs
+│   └── MAMBA_REASONING_FINETUNING_PLAN.md
+├── src/                                               # Source Code Pipeline
+│   ├── config.py                                      # Project & Model Paths Configuration
+│   ├── prepare_reasoning_dataset.py                   # Dataset Processing & CoT Formatting
+│   ├── train_mamba_reasoning.py                       # Multi-GPU Fine-Tuning Training Script
+│   ├── eval_reasoning_prompts.py                      # 100-Prompt Pre/Post CoT Evaluation
+│   ├── build_reasoning_report.py                      # Benchmark Markdown Builder
+│   ├── export_and_register_ollama.py                  # GGUF Conversion & Ollama Registration
+│   └── push_to_hub.py                                 # Hugging Face Publisher
+├── data -> /data/pocs_models_and_checkpoints/MAMBA_FINETUNING/data
+└── results -> /data/pocs_models_and_checkpoints/MAMBA_FINETUNING/results
+```
+
+---
+
+## 🛠️ Step-by-Step Proposed Changes
+
+### Component 1: Dataset Preparation (`src/prepare_reasoning_dataset.py`)
+- Load `BespokeLabs/Bespoke-Stratos-17k` / `open-thoughts/OpenThoughts-114k`.
+- Format system prompt: `"You are an advanced AI reasoning assistant powered by a Selective State Space Model. You solve complex problems step-by-step using internal reasoning traces wrapped in <think>...</think> tags."`
+- Structure response into:
+  ```
+  <think>
+  Step 1: Deconstruct the problem constraints...
+  Step 2: Derive the mathematical or algorithmic formulation...
+  </think>
+  Final Solution / Executable Code...
+  ```
+- Output splits: `train.jsonl` (15,000 items), `val.jsonl` (1,500 items), `eval_100_prompts.jsonl` (100 holdout prompts).
+
+### Component 2: Multi-GPU Training Engine (`src/train_mamba_reasoning.py`)
+- Base Model: `tiiuae/falcon-mamba-7b-instruct` or `mistralai/mamba-codestral-7b`.
+- Fine-Tuning Setup: SFTTrainer with `bf16` precision across 2x H200 GPUs.
+- Target Module Adaptations for SSM: `in_proj`, `out_proj`, `x_proj`, `dt_proj`.
+- Save adapter weights to `/data/pocs_models_and_checkpoints/MAMBA_FINETUNING/results/adapter`.
+
+### Component 3: Benchmark Evaluation & Report (`src/eval_reasoning_prompts.py`)
+- Compare Base Mamba 7B vs. Fine-Tuned Mamba Reasoning 7B across 100 holdout prompts.
+- Evaluate `<think>` CoT trigger rate, reasoning depth, and mathematical correctness.
+
+### Component 4: Export, Ollama Registration & HF Publish
+- Convert merged model to GGUF using `llama.cpp`'s `convert_hf_to_gguf.py`.
+- Register as `mamba-7b-reasoning:latest` in Ollama.
+- Upload to Hugging Face repository `namanadep/Mamba-7B-Reasoning`.
+
+---
+
+## 🔬 Verification & Validation Plan
+
+1. **Automated Training Check**: Confirm training loss convergence (e.g. initial `3.50` $\rightarrow$ final `1.20` validation loss).
+2. **CoT Reasoning Verification**: Test generated outputs for mandatory `<think>...</think>` internal reasoning blocks.
+3. **Local Ollama Functionality**: Verify instant execution via `ollama run mamba-7b-reasoning:latest`.
+4. **Hugging Face Live Verification**: Inspect model card, files, and GGUF download link on Hugging Face.