SPECIFICATION.md

Project Specification

1. Project Name

Local Advanced Fine-Tuning Pipeline for Coding LLM

2. Purpose

Provide a fully local, modular workflow to fine-tune a compact coding LLM for:

• code fixing
• debugging
• code explanation
• response confidence and relevancy signals

3. Functional Requirements

FR-1 Dataset Generation

• System must generate a JSON dataset with fields:
  • instruction
  • input
  • output
  • explanation
  • confidence
  • relevancy
• Dataset size must be constrained to 5000-10000 samples.

FR-2 Model Fine-Tuning

• System must support LoRA fine-tuning on:
  • Qwen/Qwen2.5-Coder-0.5B-Instruct (default)
• Training inputs must be tokenized and formatted from dataset records.
• Training output must be stored in a configurable output directory.

FR-3 Pipeline Orchestration

• System must provide a one-command execution script for:
  • dataset generation
  • training
  • optional uploading
• Pipeline must support skipping individual stages.

FR-4 Local Inference

• System must generate outputs from local model folder.
• Inference module must support:
  • LoRA adapter outputs
  • full model outputs
• Inference output must be valid JSON containing:
  • code
  • explanation
  • confidence
  • important_tokens
  • relevancy_score
  • hallucination
  • hallucination_check_reason
  • latency_ms

FR-5 HF Upload

• System must upload trained model artifacts to a user-specified HF repo.
• Upload should be optional and independently executable.
• System must support updating an existing HF model repo by uploading to the same repo_id.

4. Non-Functional Requirements

NFR-1 Reliability

• Scripts must fail with clear error messages for missing files/directories.

NFR-2 Configurability

• Hyperparameters and paths must be configurable via CLI.
• Pipeline defaults should be read from training_config.json.

NFR-3 Performance

• Must support limited-sample smoke run for CPU environments.
• Tokenization must use deterministic fixed-length padding for stable LoRA training labels.
• Inference should support deterministic mode by default for stable outputs.

NFR-4 Maintainability

• Modules must remain decoupled and single-purpose where possible.
• Documentation must include setup and run commands.

5. Input/Output Contracts

Dataset Generator

• Input:
  • --size (int, 5000-10000)
  • --out (path)
• Output:
  • JSON training file at --out

Trainer

• Input:
  • dataset file path
  • model name
  • hyperparameters
• Output:
  • trained model artifacts in output_dir

Inference

• Input:
  • local model path
  • prompt
  • max new tokens
• Output:
  • structured JSON to stdout
• Contract:
  • required keys: code, explanation, confidence, important_tokens, relevancy_score, hallucination, hallucination_check_reason, latency_ms

Upload

• Input:
  • model directory path
  • HF repo id
• Output:
  • model artifacts uploaded to HF repo

6. Default Configuration

• Model: Qwen/Qwen2.5-Coder-0.5B-Instruct
• Dataset size: 8000
• Epochs: 3
• Batch size: 2
• Learning rate: 1e-4
• Max length: 512

7. Validation Criteria

Project is considered runnable when:

• all scripts compile
• dataset generation succeeds
• a smoke training run completes
• inference returns valid JSON payload with required keys
• upload script accepts valid model dir and repo id

8. Known Constraints

• CPU training is slow for full dataset runs.
• HF login/token is required for upload.
• Output quality depends heavily on dataset diversity and quality.