Initial commit: Phase 1 (data prep) and Phase 2 (QLoRA fine-tuning) complete

- data/prepare_data.py builds a balanced LEDGAR clause-classification split
- training/finetune_qlora.ipynb fine-tunes Llama-3.2-1B with QLoRA, measuring
baseline vs fine-tuned accuracy (20.00% -> 94.33%)

.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+env/
+.env
+.ipynb_checkpoints/
+
+# Generated data (regenerable with data/prepare_data.py) -- keep labels.json
+data/train.jsonl
+data/val.jsonl
+data/test.jsonl
+
+# Model weights / adapters (stored on the Hugging Face Hub instead)
+*.bin
+*.safetensors
+adapters/
+outputs/
+checkpoints/
+
+# Hugging Face cache
+.cache/
+
+# Claude Code local-only settings
+.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md — Project guide for Claude Code
+
+## What we are building
+**Compliance Copilot**: an automated contract-clause classifier and compliance-review
+tool. It reads a contract, splits it into clauses, classifies each clause by type,
+checks it against compliance rules, and produces a review report.
+
+This is a portfolio project. It must be showcaseable on a resume, on GitHub, and as a
+live deployed demo. Everything must use free / open-source tools (no paid services
+beyond Claude Code itself).
+
+## The three components (each maps to one resume line)
+1. **Brain** — `Llama-3.2-1B-Instruct` fine-tuned with **QLoRA (PEFT)** to classify
+   contract clauses. (Resume line: "fine-tuned Llama-3 with QLoRA/PEFT, +X% accuracy".)
+2. **Front desk** — a **FastAPI** service with **async** endpoints, packaged in **Docker**.
+   (Resume line: "scalable asynchronous pipelines with FastAPI and Docker".)
+3. **Manager** — a **LangChain agent** that runs the end-to-end review workflow.
+   (Resume line: "automated compliance workflows with LangChain agents".)
+
+## Tech + free-tool choices (do not change without asking the user)
+- Dataset: **LEDGAR** (public contract-clause dataset) via HuggingFace `datasets`.
+- Model: `meta-llama/Llama-3.2-1B-Instruct` (small enough for free Colab GPU + free CPU serving).
+- Fine-tuning: QLoRA (4-bit) + PEFT + HuggingFace `transformers` / `trl`, run in **Google Colab** (free T4).
+- Adapter storage: **HuggingFace Hub** (free; LoRA adapter is a few MB).
+- Serving: FastAPI + Uvicorn, async endpoints.
+- Workflow: LangChain agent + tools.
+- Deploy: **HuggingFace Spaces** (free Docker Space, CPU inference).
+- Repo: GitHub.
+
+## Roadmap (build phase by phase; explain each step simply before coding)
+- [x] **Phase 1 — Data prep** (`data/prepare_data.py`): subset LEDGAR to top-10 clause
+      types, balance classes, write train/val/test JSONL in chat format. DONE.
+- [x] **Phase 2 — Fine-tune the brain** (`training/finetune_qlora.ipynb`): QLoRA fine-tune,
+      AND measure baseline (zero-shot) vs fine-tuned accuracy so the "+X%" number is REAL.
+      DONE — ran successfully in Colab. Accuracy 20.00% -> 94.33% (+74.33 pp), macro-F1
+      0.1013 -> 0.9439 (+84.26 pp). Adapter pushed to
+      `SaitejaDubbas/compliance-copilot-llama32-1b-lora`.
+- [ ] **Phase 3 — Front desk** (`app/model.py`, `app/main.py`): load base model + adapter,
+      async FastAPI `/classify` endpoint.
+- [ ] **Phase 4 — Manager** (`app/agent.py`): LangChain agent that splits a document into
+      clauses, classifies each via the model, applies simple compliance rules, writes a report.
+- [ ] **Phase 5 — Docker** (`Dockerfile`): containerize the app.
+- [ ] **Phase 6 — Deploy**: HuggingFace Spaces (Docker SDK), get a live public link.
+- [ ] **Phase 7 — Polish**: README results table with real numbers, demo GIF, resume wording.
+
+## Conventions
+- The system prompt + user-prompt template live in `data/prepare_data.py`
+  (`SYSTEM_PROMPT`, `build_user_prompt`). Training AND serving must reuse the EXACT same
+  text, or the model gets confused. If serving code needs them, import/copy them verbatim.
+- Keep the deployed model runnable on CPU (this is why we use the 1B model).
+- The "+X% accuracy" claim must always be a measured number (base zero-shot vs fine-tuned
+  on the held-out test split), never invented.
+- Explain each new step in plain language before writing code (the user likes concrete
+  analogies and step-by-step reasoning).
+
+## Current status
+Phase 1 is done (note: the LEDGAR dataset id changed from `lex_glue` to
+`coastalcph/lex_glue` — the old unnamespaced alias no longer resolves on the Hub;
+`data/prepare_data.py` and `training/finetune_qlora.ipynb` both use the new id).
+
+Phase 2 is done. HF username: `SaitejaDubbas`. Adapter repo:
+`SaitejaDubbas/compliance-copilot-llama32-1b-lora`. Three fixes were needed live in
+Colab and are now baked into `training/finetune_qlora.ipynb` so a fresh run works
+end to end: (1) TRL's `SFTConfig` renamed `max_seq_length` -> `max_length`; (2) the
+T4 computes in bfloat16, so training must use `bf16=True, fp16=False` (fp16 crashed
+with a BFloat16 gradient-unscale error); (3) the save/push cell now derives
+`HF_USERNAME` via `huggingface_hub.whoami()` right before pushing instead of trusting
+the placeholder in the config cell, so it can't 403 against a nonexistent namespace.
+See `docs/PROGRESS_LOG.md` for details.
+
+Next action: build Phase 3 — `app/model.py` + `app/main.py`, loading
+`unsloth/Llama-3.2-1B-Instruct` plus the `SaitejaDubbas/compliance-copilot-llama32-1b-lora`
+adapter behind an async FastAPI `/classify` endpoint.

README.md

@@ -0,0 +1,88 @@
+# Compliance Copilot
+
+**Automated contract-clause classification and compliance-review workflows, powered by a fine-tuned Llama-3 model.**
+
+Compliance Copilot reads a contract, breaks it into individual clauses, classifies each clause by type, checks it against a set of compliance rules, and produces a review report — all through a single API call or a web demo.
+
+> Built entirely with free and open-source tools. Trained on the public **LEDGAR** contract-clause dataset (no private data used).
+
+---
+
+## What it does
+
+Three components work together, like a small compliance team:
+
+| Component | Role | Tech |
+|-----------|------|------|
+| **The brain** | Reads a clause and predicts its type | Llama-3.2-1B fine-tuned with QLoRA (PEFT) |
+| **The front desk** | Serves predictions fast, handles many requests at once | FastAPI (async) + Docker |
+| **The manager** | Runs the end-to-end review workflow and writes the report | LangChain agent |
+
+```
+        LangChain Agent  ->  FastAPI service  ->  Fine-tuned Llama-3
+         (workflow)            (async API)          (QLoRA adapter)
+```
+
+## Results
+
+Measured on a held-out test split of LEDGAR (600 clauses, 10 clause types). Fine-tuning raised accuracy from 20% to 94%:
+
+| Setup | Accuracy | Macro-F1 |
+|-------|----------|----------|
+| Base Llama-3.2-1B (zero-shot) | 20.00% | 0.1013 |
+| Fine-tuned with QLoRA | 94.33% | 0.9439 |
+| **Improvement** | **+74.33 pp** | **+84.26 pp** |
+
+*(Numbers are measured on the held-out test split, not estimated. Adapter: [SaitejaDubbas/compliance-copilot-llama32-1b-lora](https://huggingface.co/SaitejaDubbas/compliance-copilot-llama32-1b-lora).)*
+
+## Tech stack
+
+- **Model / training:** Llama-3.2-1B-Instruct, QLoRA (4-bit), PEFT, Hugging Face `transformers` + `trl`
+- **Serving:** FastAPI, Uvicorn, async endpoints
+- **Workflow:** LangChain agent + tools
+- **Packaging & deploy:** Docker, Hugging Face Spaces (free tier)
+- **Data:** LEDGAR (via the `datasets` library)
+
+## Project structure
+
+```
+compliance-copilot/
+├── data/
+│   └── prepare_data.py       # Phase 1: build train/val/test from LEDGAR
+├── training/
+│   └── finetune_qlora.ipynb  # Phase 2: QLoRA fine-tuning + accuracy eval  (added next)
+├── app/
+│   ├── model.py              # loads model + adapter, runs inference        (added next)
+│   ├── main.py               # FastAPI async endpoints                      (added next)
+│   ├── agent.py              # LangChain compliance-review agent            (added next)
+│   └── ui.py                 # simple web demo                              (added next)
+├── Dockerfile                # Phase 5                                      (added next)
+├── requirements.txt
+└── README.md
+```
+
+## Quickstart
+
+```bash
+# 1. Build the dataset
+pip install -U datasets
+python data/prepare_data.py
+
+# 2. Fine-tune (in Google Colab, free GPU) -- see training/finetune_qlora.ipynb
+
+# 3. Run the API locally
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+
+# 4. Try it
+curl -X POST localhost:8000/classify -H "Content-Type: application/json" \
+     -d '{"clause": "The parties agree to keep all shared information confidential."}'
+```
+
+## Live demo
+
+Deployed on Hugging Face Spaces: `link added after Phase 6`
+
+## License
+
+Code released under the MIT License. LEDGAR data belongs to its original authors; the Llama-3.2 model is used under Meta's community license.

data/labels.json

@@ -0,0 +1,12 @@
+[
+  "Governing Laws",
+  "Notices",
+  "Counterparts",
+  "Entire Agreements",
+  "Severability",
+  "Survival",
+  "Amendments",
+  "Assignments",
+  "Expenses",
+  "Terms"
+]

data/prepare_data.py

@@ -0,0 +1,134 @@
+"""
+Compliance Copilot -- Phase 1: Data Preparation
+================================================
+
+Goal of this file (one sentence):
+    Take a big public dataset of real contract clauses and turn it into small,
+    clean files we can feed to our model in Phase 2.
+
+Why LEDGAR?
+    LEDGAR is a public dataset of contract provisions ("clauses"), where each
+    clause is labelled with its type (e.g. "Confidentiality", "Governing Laws",
+    "Terminations"). This is exactly the "what kind of clause is this / is it
+    compliant" problem a compliance team faces every day. It is public and
+    license-friendly, so we can safely showcase it (unlike private company data).
+
+Where to run this:
+    In Google Colab (free) or on your own laptop. It needs internet the first
+    time so it can download the dataset from the Hugging Face Hub.
+
+    Install the one thing it needs:
+        pip install -U datasets
+
+Output (all written into this ./data folder):
+    labels.json   -> the list of clause types we keep
+    train.jsonl   -> training examples (chat format, used to teach the model)
+    val.jsonl     -> validation examples (chat format, used to watch progress)
+    test.jsonl    -> held-out examples (raw text + label, used to score accuracy)
+"""
+
+import json
+import random
+from collections import Counter
+from pathlib import Path
+
+from datasets import load_dataset
+
+# ---------------------------------------------------------------------------
+# Settings you are allowed to play with
+# ---------------------------------------------------------------------------
+TOP_K_LABELS = 10           # keep only the K most common clause types
+MAX_PER_LABEL_TRAIN = 400   # cap training examples per label (keeps training fast + free)
+MAX_PER_LABEL_EVAL = 60     # cap validation/test examples per label
+SEED = 42
+OUT_DIR = Path(__file__).resolve().parent   # writes next to this script (the data/ folder)
+
+# This is the "job description" we hand the model. IMPORTANT: the SAME text must
+# be used again when we serve the model in Phase 3, otherwise it gets confused.
+# That is why we keep it here in one place and reuse it everywhere.
+SYSTEM_PROMPT = (
+    "You are a compliance assistant. You read a single contract clause and reply "
+    "with the one clause type it belongs to, and nothing else."
+)
+
+
+def build_user_prompt(clause_text: str, labels: list) -> str:
+    """Turn a clause + the menu of allowed answers into the question we ask the model."""
+    label_menu = ", ".join(labels)
+    return (
+        f"Classify the following contract clause into exactly one of these types: "
+        f"{label_menu}.\n\n"
+        f"Clause:\n{clause_text}\n\n"
+        f"Clause type:"
+    )
+# ---------------------------------------------------------------------------
+
+random.seed(SEED)
+
+
+def main() -> None:
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    print("Step 1/5  Downloading LEDGAR from the Hugging Face Hub ...")
+    ds = load_dataset("coastalcph/lex_glue", "ledgar")
+
+    # The dataset stores labels as numbers (0, 1, 2, ...). This list turns a
+    # number back into a human name, e.g. 12 -> "Confidentiality".
+    label_names = ds["train"].features["label"].names
+    print(f"          The full dataset has {len(label_names)} clause types.")
+
+    print("Step 2/5  Finding the most common clause types ...")
+    counts = Counter(ds["train"]["label"])            # how often each label appears
+    top_ids = [label_id for label_id, _ in counts.most_common(TOP_K_LABELS)]
+    kept_labels = [label_names[i] for i in top_ids]   # the names we keep
+    id_to_name = {i: label_names[i] for i in top_ids}
+    print(f"          Keeping the top {TOP_K_LABELS}: {kept_labels}")
+
+    # Save the label list so every other part of the project agrees on it.
+    (OUT_DIR / "labels.json").write_text(json.dumps(kept_labels, indent=2))
+
+    def collect(split_name: str, cap_per_label: int):
+        """Grab up to cap_per_label examples for each label so classes stay balanced."""
+        buckets = {i: [] for i in top_ids}
+        for row in ds[split_name]:
+            lid = row["label"]
+            if lid in buckets and len(buckets[lid]) < cap_per_label:
+                buckets[lid].append(row["text"])
+        pairs = [(text, id_to_name[lid]) for lid, texts in buckets.items() for text in texts]
+        random.shuffle(pairs)
+        return pairs
+
+    print("Step 3/5  Selecting + balancing examples ...")
+    train_pairs = collect("train", MAX_PER_LABEL_TRAIN)
+    val_pairs = collect("validation", MAX_PER_LABEL_EVAL)
+    test_pairs = collect("test", MAX_PER_LABEL_EVAL)
+    print(f"          train={len(train_pairs)}  val={len(val_pairs)}  test={len(test_pairs)}")
+
+    print("Step 4/5  Writing training + validation files (chat format) ...")
+
+    def write_chat(path: Path, pairs):
+        with path.open("w") as f:
+            for text, label in pairs:
+                example = {
+                    "messages": [
+                        {"role": "system", "content": SYSTEM_PROMPT},
+                        {"role": "user", "content": build_user_prompt(text, kept_labels)},
+                        {"role": "assistant", "content": label},
+                    ]
+                }
+                f.write(json.dumps(example) + "\n")
+
+    write_chat(OUT_DIR / "train.jsonl", train_pairs)
+    write_chat(OUT_DIR / "val.jsonl", val_pairs)
+
+    print("Step 5/5  Writing the test file (raw text + label, for scoring) ...")
+    with (OUT_DIR / "test.jsonl").open("w") as f:
+        for text, label in test_pairs:
+            f.write(json.dumps({"text": text, "label": label}) + "\n")
+
+    print("\nDone. Files written into:", OUT_DIR)
+    print("Next: open the Phase 2 fine-tuning notebook.")
+
+
+if __name__ == "__main__":
+    main()

docs/PROGRESS_LOG.md

@@ -0,0 +1,32 @@
+# Progress Log
+
+## Phase 2 — Fine-tune the brain (QLoRA)
+
+Ran `training/finetune_qlora.ipynb` end to end in Google Colab (T4 GPU).
+
+**Result:** fine-tuning raised accuracy from 20% to 94% on the 600-clause held-out
+test split.
+
+| Metric | Baseline (zero-shot) | Fine-tuned | Improvement |
+|--------|----------------------|------------|-------------|
+| Accuracy | 20.00% | 94.33% | +74.33 pp |
+| Macro-F1 | 0.1013 | 0.9439 | +84.26 pp |
+
+Adapter pushed to: [`SaitejaDubbas/compliance-copilot-llama32-1b-lora`](https://huggingface.co/SaitejaDubbas/compliance-copilot-llama32-1b-lora)
+
+### Fixes needed live in Colab
+
+The notebook as originally written didn't run clean on a fresh Colab session. Three
+issues surfaced and were fixed in the saved notebook so future runs work end to end:
+
+1. **`SFTConfig` argument rename.** Current TRL removed `max_seq_length` in favor of
+   `max_length`. Fixed in the training-args cell.
+2. **bf16/fp16 mismatch on the T4.** Training crashed with
+   `NotImplementedError: _amp_foreach_non_finite_check_and_unscale_cuda not
+   implemented for 'BFloat16'` because the model computes in bfloat16 but the
+   trainer was configured for fp16 mixed precision. Fixed by setting `bf16=True,
+   fp16=False` in `SFTConfig`.
+3. **Push-to-hub 403.** The save/push cell relied on a hardcoded `HF_USERNAME`
+   placeholder, which didn't match the logged-in account and got rejected. Fixed by
+   deriving the username from `huggingface_hub.whoami()` immediately before pushing,
+   so the push always targets the account actually logged into the notebook.

requirements.txt

@@ -0,0 +1,15 @@
+# Runtime dependencies for the FastAPI app + LangChain agent.
+# (Training-only tools like bitsandbytes, trl, and datasets are installed
+#  inside the Colab notebook in Phase 2, so they are not needed here.)
+
+fastapi
+uvicorn[standard]
+pydantic
+transformers
+torch
+peft
+accelerate
+langchain
+langchain-community
+gradio
+huggingface-hub

training/finetune_qlora.ipynb

@@ -0,0 +1,515 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Compliance Copilot \u2014 Phase 2: Fine-tune the Brain\n",
+    "\n",
+    "This notebook is **self-contained**: it does not read any files from the rest of\n",
+    "the repo. You can upload just this one file to a fresh Google Colab, run it top\n",
+    "to bottom, and it will rebuild the training data itself, fine-tune the model,\n",
+    "and push the result to the Hugging Face Hub.\n",
+    "\n",
+    "**Before running:** In Colab, go to `Runtime > Change runtime type` and select a\n",
+    "**T4 GPU** (free tier). Everything below assumes a GPU is available.\n",
+    "\n",
+    "**What this notebook proves (for the resume line):** we measure accuracy on the\n",
+    "same 600 held-out contract clauses *before* fine-tuning (zero-shot) and *after*\n",
+    "fine-tuning (QLoRA), so the \"+X% accuracy\" number is real, not invented."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 1 \u2014 Install the libraries\n",
+    "\n",
+    "Think of this as gathering tools before starting a job: `transformers` loads the\n",
+    "model, `peft` + `bitsandbytes` let us load and train it in 4-bit (so it fits on a\n",
+    "free GPU), `trl` gives us a ready-made trainer for chat-style fine-tuning, and\n",
+    "`datasets` / `scikit-learn` handle the data and the accuracy scoring."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install -q -U transformers peft trl bitsandbytes accelerate datasets scikit-learn\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import torch\n",
+    "\n",
+    "print(\"CUDA available:\", torch.cuda.is_available())\n",
+    "if torch.cuda.is_available():\n",
+    "    print(\"GPU:\", torch.cuda.get_device_name(0))\n",
+    "else:\n",
+    "    print(\"No GPU detected. Go to Runtime > Change runtime type > select a GPU (T4), then re-run.\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 2 \u2014 Log in to Hugging Face\n",
+    "\n",
+    "We need a Hugging Face account token for two reasons: to download the base\n",
+    "model, and \u2014 at the very end \u2014 to upload (\"push\") our trained adapter back to\n",
+    "the Hub so Phase 3 can load it. Running the cell below shows a login widget;\n",
+    "paste a token with **write** access (create one at\n",
+    "huggingface.co/settings/tokens)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from huggingface_hub import notebook_login\n",
+    "\n",
+    "notebook_login()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 3 \u2014 Configuration\n",
+    "\n",
+    "Everything you might want to change lives in one place. `BASE_MODEL` is the\n",
+    "small 1-billion-parameter model we fine-tune \u2014 it's an open, ungated mirror of\n",
+    "Llama-3.2-1B-Instruct, so it downloads without needing Meta's access-request\n",
+    "form. Set `HF_USERNAME` to your Hugging Face username; the trained adapter gets\n",
+    "uploaded to `<HF_USERNAME>/compliance-copilot-llama32-1b-lora`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import random\n",
+    "from collections import Counter\n",
+    "\n",
+    "import numpy as np\n",
+    "from datasets import load_dataset, Dataset\n",
+    "from transformers import (\n",
+    "    AutoModelForCausalLM,\n",
+    "    AutoTokenizer,\n",
+    "    BitsAndBytesConfig,\n",
+    ")\n",
+    "from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training\n",
+    "from trl import SFTConfig, SFTTrainer\n",
+    "from sklearn.metrics import accuracy_score, f1_score\n",
+    "from tqdm.auto import tqdm\n",
+    "\n",
+    "# --- Things you are likely to change ---\n",
+    "BASE_MODEL = \"unsloth/Llama-3.2-1B-Instruct\"  # ungated open copy of Llama-3.2-1B-Instruct\n",
+    "HF_USERNAME = \"SaitejaDubbas\"  # <-- your Hugging Face username\n",
+    "ADAPTER_REPO = f\"{HF_USERNAME}/compliance-copilot-llama32-1b-lora\"\n",
+    "\n",
+    "# --- Data settings copied from data/prepare_data.py (must match Phase 1 exactly) ---\n",
+    "DATASET_ID = \"coastalcph/lex_glue\"\n",
+    "DATASET_CONFIG = \"ledgar\"\n",
+    "TOP_K_LABELS = 10\n",
+    "MAX_PER_LABEL_TRAIN = 400\n",
+    "MAX_PER_LABEL_EVAL = 60\n",
+    "SEED = 42\n",
+    "\n",
+    "random.seed(SEED)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 3b \u2014 Rebuild the dataset (same recipe as `data/prepare_data.py`)\n",
+    "\n",
+    "This notebook can't read files from the repo, so we rebuild the exact same\n",
+    "train/val/test split here, using the identical logic, seed, and prompt wording\n",
+    "as `data/prepare_data.py`. That match matters: if the wording here drifted from\n",
+    "what Phase 3 uses to serve the model, the fine-tuned model would see unfamiliar\n",
+    "phrasing at inference time and get confused \u2014 like practicing for an interview\n",
+    "with one set of questions and then being asked completely different ones on the\n",
+    "day.\n",
+    "\n",
+    "We download LEDGAR, keep the 10 most common clause types, and balance each\n",
+    "split so no single clause type dominates training."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Copied verbatim from data/prepare_data.py so training and serving never\n",
+    "# disagree on the wording the model was taught with.\n",
+    "SYSTEM_PROMPT = (\n",
+    "    \"You are a compliance assistant. You read a single contract clause and reply \"\n",
+    "    \"with the one clause type it belongs to, and nothing else.\"\n",
+    ")\n",
+    "\n",
+    "\n",
+    "def build_user_prompt(clause_text: str, labels: list) -> str:\n",
+    "    label_menu = \", \".join(labels)\n",
+    "    return (\n",
+    "        f\"Classify the following contract clause into exactly one of these types: \"\n",
+    "        f\"{label_menu}.\\n\\n\"\n",
+    "        f\"Clause:\\n{clause_text}\\n\\n\"\n",
+    "        f\"Clause type:\"\n",
+    "    )\n",
+    "\n",
+    "\n",
+    "print(\"Downloading LEDGAR ...\")\n",
+    "ds = load_dataset(DATASET_ID, DATASET_CONFIG)\n",
+    "\n",
+    "label_names = ds[\"train\"].features[\"label\"].names\n",
+    "counts = Counter(ds[\"train\"][\"label\"])\n",
+    "top_ids = [label_id for label_id, _ in counts.most_common(TOP_K_LABELS)]\n",
+    "kept_labels = [label_names[i] for i in top_ids]\n",
+    "id_to_name = {i: label_names[i] for i in top_ids}\n",
+    "print(f\"Keeping the top {TOP_K_LABELS} labels: {kept_labels}\")\n",
+    "\n",
+    "\n",
+    "def collect(split_name: str, cap_per_label: int):\n",
+    "    buckets = {i: [] for i in top_ids}\n",
+    "    for row in ds[split_name]:\n",
+    "        lid = row[\"label\"]\n",
+    "        if lid in buckets and len(buckets[lid]) < cap_per_label:\n",
+    "            buckets[lid].append(row[\"text\"])\n",
+    "    pairs = [(text, id_to_name[lid]) for lid, texts in buckets.items() for text in texts]\n",
+    "    random.shuffle(pairs)\n",
+    "    return pairs\n",
+    "\n",
+    "\n",
+    "train_pairs = collect(\"train\", MAX_PER_LABEL_TRAIN)\n",
+    "val_pairs = collect(\"validation\", MAX_PER_LABEL_EVAL)\n",
+    "test_pairs = collect(\"test\", MAX_PER_LABEL_EVAL)\n",
+    "print(f\"train={len(train_pairs)}  val={len(val_pairs)}  test={len(test_pairs)}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 4 \u2014 Baseline (zero-shot) evaluation\n",
+    "\n",
+    "Before we teach the model anything, let's see how well it does \"cold\" \u2014 just\n",
+    "handed the clause and the list of possible types, with no training on our\n",
+    "data. This is the \"before\" photo. We load the base model in 4-bit precision (a\n",
+    "compressed format that trades a little precision for using ~4x less GPU\n",
+    "memory, which is what makes this fit on a free T4), then ask it to classify\n",
+    "all 600 held-out test clauses."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL)\n",
+    "if tokenizer.pad_token is None:\n",
+    "    tokenizer.pad_token = tokenizer.eos_token\n",
+    "tokenizer.padding_side = \"left\"  # required for correct batched generation\n",
+    "\n",
+    "bnb_config = BitsAndBytesConfig(\n",
+    "    load_in_4bit=True,\n",
+    "    bnb_4bit_quant_type=\"nf4\",\n",
+    "    bnb_4bit_compute_dtype=torch.float16,\n",
+    "    bnb_4bit_use_double_quant=True,\n",
+    ")\n",
+    "\n",
+    "model = AutoModelForCausalLM.from_pretrained(\n",
+    "    BASE_MODEL,\n",
+    "    quantization_config=bnb_config,\n",
+    "    device_map=\"auto\",\n",
+    ")\n",
+    "model.config.pad_token_id = tokenizer.pad_token_id\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import difflib\n",
+    "\n",
+    "\n",
+    "def parse_prediction(raw_text: str, labels: list) -> str:\n",
+    "    \"\"\"Turn whatever text the model generated into the closest known label.\"\"\"\n",
+    "    cleaned = raw_text.strip()\n",
+    "    for label in labels:\n",
+    "        if cleaned.lower() == label.lower():\n",
+    "            return label\n",
+    "    for label in labels:\n",
+    "        if label.lower() in cleaned.lower():\n",
+    "            return label\n",
+    "    close = difflib.get_close_matches(cleaned, labels, n=1, cutoff=0.0)\n",
+    "    return close[0] if close else labels[0]\n",
+    "\n",
+    "\n",
+    "@torch.no_grad()\n",
+    "def evaluate(model, tokenizer, pairs, labels, batch_size=16, max_new_tokens=8):\n",
+    "    model.eval()\n",
+    "    preds, golds = [], []\n",
+    "    for i in tqdm(range(0, len(pairs), batch_size)):\n",
+    "        batch = pairs[i : i + batch_size]\n",
+    "        prompts = [\n",
+    "            tokenizer.apply_chat_template(\n",
+    "                [\n",
+    "                    {\"role\": \"system\", \"content\": SYSTEM_PROMPT},\n",
+    "                    {\"role\": \"user\", \"content\": build_user_prompt(text, labels)},\n",
+    "                ],\n",
+    "                tokenize=False,\n",
+    "                add_generation_prompt=True,\n",
+    "            )\n",
+    "            for text, _ in batch\n",
+    "        ]\n",
+    "        inputs = tokenizer(\n",
+    "            prompts, return_tensors=\"pt\", padding=True, truncation=True, max_length=1024\n",
+    "        ).to(model.device)\n",
+    "        out = model.generate(\n",
+    "            **inputs,\n",
+    "            max_new_tokens=max_new_tokens,\n",
+    "            do_sample=False,\n",
+    "            pad_token_id=tokenizer.pad_token_id,\n",
+    "        )\n",
+    "        new_tokens = out[:, inputs[\"input_ids\"].shape[1] :]\n",
+    "        decoded = tokenizer.batch_decode(new_tokens, skip_special_tokens=True)\n",
+    "        for (text, gold), raw in zip(batch, decoded):\n",
+    "            preds.append(parse_prediction(raw, labels))\n",
+    "            golds.append(gold)\n",
+    "    acc = accuracy_score(golds, preds)\n",
+    "    f1 = f1_score(golds, preds, labels=labels, average=\"macro\", zero_division=0)\n",
+    "    return acc, f1, preds, golds\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"Running BASELINE (zero-shot) evaluation on the 600 held-out test clauses ...\")\n",
+    "baseline_acc, baseline_f1, _, _ = evaluate(model, tokenizer, test_pairs, kept_labels)\n",
+    "print(f\"\\nBaseline  accuracy: {baseline_acc:.4f}   macro-F1: {baseline_f1:.4f}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 5 \u2014 Fine-tune with QLoRA\n",
+    "\n",
+    "Instead of retraining all 1 billion parameters (slow, memory-hungry, and\n",
+    "unnecessary), QLoRA freezes the base model and trains small \"adapter\"\n",
+    "matrices bolted onto the attention layers \u2014 like adding sticky notes to a\n",
+    "textbook instead of rewriting it. `r=16` / `alpha=32` control how much\n",
+    "capacity those sticky notes have. We train for 2 passes (epochs) over the\n",
+    "4,000 training examples."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model = prepare_model_for_kbit_training(model)\n",
+    "\n",
+    "lora_config = LoraConfig(\n",
+    "    r=16,\n",
+    "    lora_alpha=32,\n",
+    "    lora_dropout=0.05,\n",
+    "    target_modules=[\"q_proj\", \"k_proj\", \"v_proj\", \"o_proj\"],\n",
+    "    task_type=\"CAUSAL_LM\",\n",
+    "    bias=\"none\",\n",
+    ")\n",
+    "\n",
+    "model = get_peft_model(model, lora_config)\n",
+    "model.print_trainable_parameters()\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def to_chat_examples(pairs):\n",
+    "    return [\n",
+    "        {\n",
+    "            \"messages\": [\n",
+    "                {\"role\": \"system\", \"content\": SYSTEM_PROMPT},\n",
+    "                {\"role\": \"user\", \"content\": build_user_prompt(text, kept_labels)},\n",
+    "                {\"role\": \"assistant\", \"content\": label},\n",
+    "            ]\n",
+    "        }\n",
+    "        for text, label in pairs\n",
+    "    ]\n",
+    "\n",
+    "\n",
+    "def add_text_field(example):\n",
+    "    return {\"text\": tokenizer.apply_chat_template(example[\"messages\"], tokenize=False)}\n",
+    "\n",
+    "\n",
+    "train_ds = Dataset.from_list(to_chat_examples(train_pairs)).map(add_text_field)\n",
+    "val_ds = Dataset.from_list(to_chat_examples(val_pairs)).map(add_text_field)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tokenizer.padding_side = \"right\"  # standard for training\n",
+    "\n",
+    "sft_config = SFTConfig(\n",
+    "    output_dir=\"qlora-out\",\n",
+    "    num_train_epochs=2,\n",
+    "    per_device_train_batch_size=4,\n",
+    "    gradient_accumulation_steps=4,\n",
+    "    learning_rate=2e-4,\n",
+    "    bf16=True,\n",
+    "    fp16=False,\n",
+    "    logging_steps=20,\n",
+    "    eval_strategy=\"epoch\",\n",
+    "    save_strategy=\"no\",\n",
+    "    report_to=\"none\",\n",
+    "    dataset_text_field=\"text\",\n",
+    "    max_length=1024,\n",
+    "    packing=False,\n",
+    ")\n",
+    "\n",
+    "trainer = SFTTrainer(\n",
+    "    model=model,\n",
+    "    train_dataset=train_ds,\n",
+    "    eval_dataset=val_ds,\n",
+    "    args=sft_config,\n",
+    ")\n",
+    "\n",
+    "trainer.train()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 6 \u2014 Fine-tuned evaluation\n",
+    "\n",
+    "Now we run the *exact same* evaluation function, on the *exact same* 600 test\n",
+    "clauses, but with the trained adapter active. This is the \"after\" photo \u2014\n",
+    "directly comparable to Step 4 because nothing else changed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tokenizer.padding_side = \"left\"  # back to left-padding for generation\n",
+    "print(\"Running FINE-TUNED evaluation on the same 600 held-out test clauses ...\")\n",
+    "finetuned_acc, finetuned_f1, _, _ = evaluate(model, tokenizer, test_pairs, kept_labels)\n",
+    "print(f\"\\nFine-tuned  accuracy: {finetuned_acc:.4f}   macro-F1: {finetuned_f1:.4f}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 7 \u2014 Results: baseline vs fine-tuned\n",
+    "\n",
+    "This is the number that goes on the resume. It's measured, not invented \u2014\n",
+    "both rows below ran on the identical held-out test set."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(\"=\" * 50)\n",
+    "print(f\"{'Metric':<12}{'Baseline':>12}{'Fine-tuned':>14}{'Improvement':>14}\")\n",
+    "print(\"-\" * 50)\n",
+    "print(\n",
+    "    f\"{'Accuracy':<12}{baseline_acc:>12.4f}{finetuned_acc:>14.4f}\"\n",
+    "    f\"{(finetuned_acc - baseline_acc) * 100:>13.2f}pp\"\n",
+    ")\n",
+    "print(\n",
+    "    f\"{'Macro-F1':<12}{baseline_f1:>12.4f}{finetuned_f1:>14.4f}\"\n",
+    "    f\"{(finetuned_f1 - baseline_f1) * 100:>13.2f}pp\"\n",
+    ")\n",
+    "print(\"=\" * 50)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 8 \u2014 Save and publish the adapter\n",
+    "\n",
+    "The LoRA adapter is tiny (a few MB, since we only trained the sticky notes,\n",
+    "not the whole textbook), so we save it locally and push it to your Hugging\n",
+    "Face Hub account. Phase 3's FastAPI service will load the base model plus\n",
+    "this adapter by its Hub repo id \u2014 `<HF_USERNAME>/compliance-copilot-llama32-1b-lora`.\n",
+    "\n",
+    "The cell below re-derives `HF_USERNAME` from your logged-in token via `whoami()` right before pushing, so a stale placeholder value in Step 3 can never cause a push to the wrong (nonexistent) namespace."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from huggingface_hub import whoami\n",
+    "\n",
+    "HF_USERNAME = whoami()[\"name\"]\n",
+    "ADAPTER_REPO = f\"{HF_USERNAME}/compliance-copilot-llama32-1b-lora\"\n",
+    "\n",
+    "LOCAL_ADAPTER_DIR = \"compliance-copilot-lora-adapter\"\n",
+    "\n",
+    "model.save_pretrained(LOCAL_ADAPTER_DIR)\n",
+    "tokenizer.save_pretrained(LOCAL_ADAPTER_DIR)\n",
+    "\n",
+    "print(f\"Pushing adapter + tokenizer to https://huggingface.co/{ADAPTER_REPO} ...\")\n",
+    "model.push_to_hub(ADAPTER_REPO)\n",
+    "tokenizer.push_to_hub(ADAPTER_REPO)\n",
+    "print(\"Done. Use this repo id in Phase 3 (app/model.py) to load the adapter.\")\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "provenance": [],
+   "gpuType": "T4"
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}