Update README.md

README.md

@@ -1,199 +1,233 @@
 ---
-library_name: transformers
-tags: []
+library_name: peft
+base_model: microsoft/Phi-3-mini-4k-instruct
+tags:
+  - code-review
+  - qlora
+  - lora
+  - fine-tuned
+  - code-analysis
+  - phi-3
+license: mit
+language:
+  - en
+pipeline_tag: text-generation
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
-
+# Model Card for phi3-mini-code-reviewer
 
+A QLoRA fine-tuned version of `microsoft/Phi-3-mini-4k-instruct`, specialised to review short
+Python functions and return a **structured JSON code review** — issues by category and severity,
+actionable fix suggestions, and an overall approve/request-changes verdict.
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
-
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+This model takes a Python function as input and returns a strict JSON review object, similar to
+a first-pass automated code reviewer. It was fine-tuned to close the gap between a general-purpose
+instruction model's inconsistent, prose-heavy code commentary and a schema-conformant, structured
+review a review-automation pipeline can actually parse and act on.
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+- **Developed by:** Themal De Silva
+- **Model type:** Causal decoder-only LLM, LoRA-adapted (merged)
+- **Language(s):** English (input/output), Python (code domain)
+- **License:** MIT (inherited from base model)
+- **Finetuned from model:** [microsoft/Phi-3-mini-4k-instruct](https://huggingface.co/microsoft/Phi-3-mini-4k-instruct)
 
-### Model Sources [optional]
+### Model Sources
 
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- **Repository:** CDAZZDEV-MLE-Themal/task2_genai (see notebook `task2_finetuning.ipynb`)
 
 ## Uses
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
 ### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+Given a Python function (roughly 15–45 lines) as the user turn, the model returns a JSON object:
 
-[More Information Needed]
+```json
+{
+  "issues": [
+    {"category": "bug|security|performance|style|readability",
+     "severity": "critical|major|minor",
+     "line_hint": "<short quote or line description>",
+     "suggestion": "<specific, actionable fix>"}
+  ],
+  "overall_verdict": "approve|request_changes",
+  "summary": "<2-3 sentence summary>"
+}
+```
 
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
+Intended as a first-pass automated reviewer to flag likely issues for a human reviewer to confirm
+— not a replacement for human code review.
 
 ### Out-of-Scope Use
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
+- Not evaluated on languages other than Python, or on files longer than ~45 lines / outside a
+  4096-token context.
+- Not a security-audit tool: manual review found the model under-detects security issues
+  relative to bug/style issues (see Evaluation below) — do not rely on it as a sole security gate.
+- Not intended for general-purpose chat; it was trained exclusively on the code-review task and
+  its outputs outside that format are unvalidated.
 
 ## Bias, Risks, and Limitations
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
+- **Schema drift:** in manual testing, most outputs used categories/severities close to but not
+  strictly matching the intended enum (e.g. `"Medium"` instead of `"major"`) — downstream
+  consumers should validate/normalise the output rather than assume strict enum compliance.
+- **Under-detection of security issues:** the training data (100+ teacher-generated examples)
+  under-represented security-critical scenarios relative to bugs/style; the model is more likely
+  to miss a real vulnerability than to hallucinate one, but it does miss some (e.g. failed to
+  flag an `eval()` injection vulnerability in one held-out test case).
+- **Small fine-tuning set:** trained on ~85 examples (90 train / 10 val / 10 test split from ~105
+  generated), which limits generalisation to code patterns outside the ~20 scenario types used
+  for data generation (see Training Data below).
+- **Occasional hallucination:** manual review of 10 held-out outputs found 1 hallucinated issue
+  (an invented stack-overflow concern in code with no recursion), a 10% rate in that sample.
 
 ### Recommendations
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+Treat outputs as a first-pass triage signal, always paired with human review, especially for
+security-sensitive code. Validate/coerce the returned category and severity fields against the
+intended enum before using them programmatically.
 
 ## How to Get Started with the Model
 
-Use the code below to get started with the model.
-
-[More Information Needed]
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+import torch
+
+model_id = "Themal/phi3-mini-code-reviewer"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(model_id, dtype=torch.bfloat16, device_map="auto")
+
+system_prompt = (
+    "You are an automated Python code reviewer. Given a code snippet, respond with a "
+    "single strict JSON object: issues (category, severity, line_hint, suggestion), "
+    "overall_verdict, and summary. No text outside the JSON."
+)
+code_snippet = '''def divide(a, b):
+    return a / b
+'''
+
+chat = [{"role": "system", "content": system_prompt},
+        {"role": "user", "content": code_snippet}]
+prompt = tokenizer.apply_chat_template(chat, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+out = model.generate(**inputs, max_new_tokens=400, do_sample=False, pad_token_id=tokenizer.eos_token_id)
+print(tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
+```
 
 ## Training Details
 
 ### Training Data
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
+~105 synthetic (code, review) pairs generated by `openai/gpt-oss-120b` (teacher model, via Groq)
+across 20 hand-written scenario seeds (Flask endpoints, pandas pipelines, retry wrappers, JWT
+auth, CSV parsing, thread pools, etc.) crossed with 5 issue-mix instructions, each example
+containing 1–3 deliberately planted realistic issues. Diversity was checked via prompt-length
+distribution, issue-category frequency, and scenario coverage before training. Split 80/10/10
+into train/validation/test.
 
 ### Training Procedure
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
+QLoRA fine-tuning: base model loaded in 4-bit NF4 quantization (bitsandbytes, double quant, bf16
+compute dtype), LoRA adapters applied to all attention and MLP projection layers, trained for 3
+epochs, then merged into the base model at full (bf16) precision post-training (adapters were
+merged onto a freshly reloaded full-precision copy of the base model rather than the 4-bit
+training copy, to avoid known merge instability with quantized layers).
 
-[More Information Needed]
+#### Preprocessing
 
+Examples formatted using the base model's native chat template
+(`<|system|>...<|user|>...<|assistant|>...`), with the assistant turn set to the reference
+review's JSON serialised as a string.
 
 #### Training Hyperparameters
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+- **Training regime:** bf16 compute dtype, 4-bit NF4 quantized base weights during training
+- **LoRA rank (r):** 16
+- **LoRA alpha:** 32
+- **LoRA dropout:** 0.05
+- **Target modules:** q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
+- **Learning rate:** 2e-4, cosine schedule, 3% warmup
+- **Epochs:** 3
+- **Batch size:** 2 (per device), gradient accumulation 8 (effective batch size 16)
+- **Max sequence length:** 1024 tokens
 
-#### Speeds, Sizes, Times [optional]
+#### Speeds, Sizes, Times
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+- **Hardware:** single Google Colab T4 GPU (free tier)
+- **Trainable parameters:** 8,912,896 / 3,829,992,448 total (0.23%)
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
 ### Testing Data, Factors & Metrics
 
 #### Testing Data
 
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
+10 held-out examples from the same generation process as training data (never seen during
+training or validation).
 
 #### Metrics
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
+ROUGE-L (F1), BERTScore (F1), and LLM-as-judge (`openai/gpt-oss-120b`) scoring issue_detection,
+json_validity, and actionability on a 1–5 scale, plus a manual hallucination review of 10
+fine-tuned outputs labelled correct/partial/hallucinated.
 
 ### Results
 
-[More Information Needed]
-
-#### Summary
-
+| Metric | Base (Phi-3-mini, no fine-tuning) | Fine-tuned |
+|---|---|---|
+| BERTScore F1 | 0.884 | 0.888 |
+| LLM-judge: issue_detection (1-5) | 1.30 | 1.80 |
+| LLM-judge: json_validity (1-5) | 4.40 | 4.70 |
+| LLM-judge: actionability (1-5) | 2.60 | 2.90 |
 
+Manual review of 10 fine-tuned outputs: 6 correct, 3 partial, 1 hallucinated (10% hallucination
+rate).
 
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
+#### Summary
 
-[More Information Needed]
+Fine-tuning improved every measured dimension, most notably issue_detection (+0.5) and
+actionability (+0.3). The main remaining gap is schema conformance — outputs are valid JSON but
+frequently drift from the intended category/severity enum — and under-detection of
+security-critical issues specifically, traced to under-representation of security scenarios in
+the training data. See the full evaluation notebook for per-example detail.
 
 ## Environmental Impact
 
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+- **Hardware Type:** NVIDIA T4 (Google Colab free tier)
+- **Hours used:** < 1 hour (QLoRA fine-tuning, 3 epochs, ~85 training examples)
+- **Cloud Provider:** Google Cloud (via Colab)
+- **Compute Region:** Unknown (Colab-assigned)
+- **Carbon Emitted:** Not measured; given the short training time and single T4, expected to be
+  minimal relative to full fine-tuning or larger models.
 
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
+## Technical Specifications
 
 ### Model Architecture and Objective
 
-[More Information Needed]
+Decoder-only transformer (Phi-3-mini architecture, 3.8B parameters), causal language modeling
+objective, adapted via low-rank (LoRA) weight updates on attention and MLP projections, merged
+into the base weights post-training. Objective during fine-tuning: supervised next-token
+prediction on (code, structured-JSON-review) chat-formatted pairs.
 
 ### Compute Infrastructure
 
-[More Information Needed]
-
 #### Hardware
 
-[More Information Needed]
+Single NVIDIA T4 GPU, Google Colab free tier.
 
 #### Software
 
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
+`transformers`, `peft`, `bitsandbytes` (4-bit NF4 quantization), `trl` (SFTTrainer), `datasets`.
 
-## Model Card Authors [optional]
+## Citation
 
-[More Information Needed]
+This model was produced as part of a technical assessment (Ceylon Dazzling Dev Holding Senior
+MLE Assessment, Task 2). No formal publication.
 
 ## Model Card Contact
 
-[More Information Needed]
+Themal De Silva