v1.3.0

.gitlab-ci.yml

@@ -1,3 +1,278 @@
+include:
+  - template: Jobs/SAST.gitlab-ci.yml
+  - template: Jobs/Secret-Detection.gitlab-ci.yml
+
+# Run merge request pipelines (lint/test/security + enforcement on the MR), web
+# (manual) pipelines, and push pipelines on integration branches (export/*) so the
+# SAST baseline keeps being published. Plain feature-branch pushes create no
+# pipeline, which also avoids duplicate branch + MR pipelines.
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_PIPELINE_SOURCE == "web"
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH =~ /^export\//
+
+stages:
+  - lint
+  - test
+  - security-gate
+  - deploy
+
+variables:
+  UV_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/uv"
+  GIT_DEPTH: "1"
+  PYTEST_MARKERS: "not slow"
+
+lint:format:
+  extends: .skip_docs_only
+  stage: lint
+  tags:
+    - lint
+  cache:
+    key: lint-uv-cache
+    paths:
+      - .cache/uv/
+    policy: pull-push
+  before_script:
+    - export PATH="${HOME}/.local/bin:${PATH}"
+  script:
+    - uvx isort@8.0.1 --check-only onecomp/ vllm_plugins/
+    - uvx black@26.5.1 --check onecomp/ vllm_plugins/
+
+# Skip jobs when the merge request changes docs/markdown only (**/*.md, docs/**).
+# GitLab changes has no negated globs, so we whitelist non-doc paths instead.
+# Always compare the whole MR diff against the target branch: comparing against
+# $CI_COMMIT_BEFORE_SHA breaks when it is the all-zero SHA (first MR pipeline),
+# because GitLab validates every rule's compare_to ref at pipeline creation.
+.skip_docs_only_paths: &skip_docs_only_paths
+  - onecomp/**/*
+  - tests/**/*
+  - vllm_plugins/**/*
+  - example/**/*
+  - scripts/**/*
+  - pyproject.toml
+  - uv.lock
+
+.skip_docs_only:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "web"
+      when: on_success
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        compare_to: 'refs/heads/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME'
+        paths: *skip_docs_only_paths
+      when: on_success
+    - when: never
+
+.cluster_job:
+  stage: test
+  extends: .skip_docs_only
+  tags:
+    - cluster
+  before_script:
+    - |
+      for var in \
+        CI_BASTION_HOST CI_CLUSTER_HOST CI_CLUSTER_USER ONECOMP_REPO \
+        CI_SLURM_PARTITION CI_SLURM_MEM CI_SLURM_CPUS CI_SLURM_TIME CI_SLURM_GPUS \
+        CI_UV_VENV CI_TORCH_EXTRA; do
+        eval "test -n \"\${${var}:-}\" || { echo \"Set ${var} in CI/CD Variables\" >&2; exit 1; }"
+      done
+
+# Export job env safely (printf %q), then pipe cluster_test.sh to remote bash -s.
+# Runner env vars are not forwarded over SSH automatically.
+.cluster_ssh:
+  script:
+    - |
+      {
+        printf 'export ONECOMP_REPO=%q\n' "${ONECOMP_REPO}"
+        printf 'export CI_COMMIT_SHA=%q\n' "${CI_COMMIT_SHA}"
+        printf 'export CI_COMMIT_REF_NAME=%q\n' "${CI_COMMIT_REF_NAME:-}"
+        printf 'export CI_JOB_TOKEN=%q\n' "${CI_JOB_TOKEN}"
+        printf 'export CI_SERVER_HOST=%q\n' "${CI_SERVER_HOST}"
+        printf 'export CI_PROJECT_PATH=%q\n' "${CI_PROJECT_PATH}"
+        printf 'export CLUSTER_MODE=%q\n' "${CLUSTER_MODE:-test}"
+        printf 'export SKIP_UV_SYNC=%q\n' "${SKIP_UV_SYNC:-0}"
+        printf 'export JOB_LABEL=%q\n' "${JOB_LABEL:-test}"
+        printf 'export PYTEST_TARGET=%q\n' "${PYTEST_TARGET:-tests/}"
+        printf 'export PYTEST_MARKERS=%q\n' "${PYTEST_MARKERS:-}"
+        printf 'export CI_SLURM_PARTITION=%q\n' "${CI_SLURM_PARTITION}"
+        printf 'export CI_SLURM_MEM=%q\n' "${CI_SLURM_MEM}"
+        printf 'export CI_SLURM_CPUS=%q\n' "${CI_SLURM_CPUS}"
+        printf 'export CI_SLURM_TIME=%q\n' "${CI_SLURM_TIME}"
+        printf 'export CI_SLURM_GPUS=%q\n' "${CI_SLURM_GPUS}"
+        printf 'export CI_SLURM_EXCLUDE=%q\n' "${CI_SLURM_EXCLUDE:-}"
+        printf 'export CI_UV_VENV=%q\n' "${CI_UV_VENV}"
+        printf 'export CI_TORCH_EXTRA=%q\n' "${CI_TORCH_EXTRA}"
+        cat scripts/cluster_test.sh
+      } | ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new \
+        "${CI_CLUSTER_USER}@${CI_BASTION_HOST}" \
+        "ssh -o BatchMode=yes ${CI_CLUSTER_USER}@${CI_CLUSTER_HOST} bash -s"
+
+# Lightweight connectivity check only; does not run cluster_test.sh.
+test:cluster-smoke:
+  extends: .cluster_job
+  script:
+    - |
+      ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new \
+        "${CI_CLUSTER_USER}@${CI_BASTION_HOST}" \
+        "ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new ${CI_CLUSTER_USER}@${CI_CLUSTER_HOST} bash -s" \
+        < scripts/cluster_smoke.sh
+
+# One shared env sync (CLUSTER_MODE=setup); pytest shards reuse it via SKIP_UV_SYNC=1.
+test:cluster-setup:
+  extends:
+    - .cluster_job
+    - .cluster_ssh
+  timeout: 3h
+  variables:
+    CLUSTER_MODE: setup
+    JOB_LABEL: setup
+
+test:onecomp:
+  extends:
+    - .cluster_job
+    - .cluster_ssh
+  needs:
+    - test:cluster-setup # shards wait for env sync, not for smoke
+  timeout: 13h
+  variables:
+    CLUSTER_MODE: test
+    SKIP_UV_SYNC: "1"
+  # One job definition → four parallel pytest jobs (JOB_LABEL + PYTEST_TARGET only).
+  parallel:
+    matrix:
+      - JOB_LABEL: quantizer
+        PYTEST_TARGET: "tests/onecomp/quantizer/"
+      - JOB_LABEL: pre-process
+        PYTEST_TARGET: "tests/onecomp/pre_process/ tests/onecomp/calibration/ tests/onecomp/lpcd/"
+      - JOB_LABEL: core
+        PYTEST_TARGET: "tests/onecomp/runner/ tests/onecomp/post_process/ tests/onecomp/utils/ tests/onecomp/test_make_grouped_module.py tests/onecomp/test_runner_check.py tests/onecomp/test_eval_quantized_vs_dequantized.py tests/onecomp/test_qep_general_consistency.py tests/onecomp/test_cumulative_error_regression.py tests/onecomp/test_qep_gptq_regression.py"
+      - JOB_LABEL: vllm
+        PYTEST_TARGET: "tests/vllm_plugins/"
+
+# Ensure the security jobs run in merge request pipelines and on export/* pushes
+# (the managed templates' default rules are branch-oriented). Overrides only the
+# rules; security scans intentionally run regardless of docs-only changes.
+.security_rules:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_PIPELINE_SOURCE == "web"
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH =~ /^export\//
+
+# Surface analyzer infra errors instead of silently passing.
+secret_detection:
+  allow_failure: false
+  rules: !reference [.security_rules, rules]
+
+semgrep-sast:
+  allow_failure: false
+  rules: !reference [.security_rules, rules]
+
+# Fail the pipeline when secret detection reports any finding.
+# The analyzer exits 0 even on findings, so we gate on its report.
+secret-detection-gate:
+  stage: security-gate
+  rules: !reference [.security_rules, rules]
+  needs:
+    - job: secret_detection
+      artifacts: true
+  image: alpine:3
+  before_script:
+    - apk add --no-cache jq
+  script:
+    - test -f gl-secret-detection-report.json || { echo "secret detection report not found"; exit 1; }
+    - count=$(jq '[.vulnerabilities[]] | length' gl-secret-detection-report.json)
+    - echo "secret detection findings=$count"
+    - >
+      if [ "$count" -gt 0 ]; then
+        echo "Secrets detected. Failing the pipeline.";
+        jq -r '.vulnerabilities[] | "- \(.message) (\(.location.file):\(.location.start_line))"' gl-secret-detection-report.json;
+        exit 1;
+      fi
+
+# Fail only when this branch introduces NEW High/Critical SAST findings,
+# compared with the baseline branch's latest SAST report.
+# Signature for matching: severity + semgrep rule id + file (line-shift tolerant).
+#
+# Baseline ref is resolved dynamically (no hard-coded branch name):
+#   1. the merge request target branch (CI_MERGE_REQUEST_TARGET_BRANCH_NAME), else
+#   2. an explicit override (SAST_BASELINE_REF), else
+#   3. none -> enforcement skipped (report only).
+# A direct push build of an integration branch (matching SAST_BASELINE_GLOB,
+# e.g. export/*) is informational, so it stays green and keeps publishing a
+# baseline report for future merge requests.
+sast-gate:
+  stage: security-gate
+  rules: !reference [.security_rules, rules]
+  needs:
+    - job: semgrep-sast
+      artifacts: true
+  image: alpine:3
+  variables:
+    # Integration branches (shell glob) that only publish a baseline on push.
+    SAST_BASELINE_GLOB: "export/*"
+    # Optional explicit baseline ref for non-MR pipelines (empty = none).
+    SAST_BASELINE_REF: ""
+  before_script:
+    - apk add --no-cache jq curl
+  script:
+    - |
+      set -eu
+      test -f gl-sast-report.json || { echo "sast report not found"; exit 1; }
+
+      SIG='[.vulnerabilities[] | select(.severity=="High" or .severity=="Critical") | (.severity + "|" + ((.identifiers[0].value // "?")|tostring) + "|" + (.location.file // "?"))] | unique'
+
+      total=$(jq '[.vulnerabilities[] | select(.severity=="High" or .severity=="Critical")] | length' gl-sast-report.json)
+      echo "current High/Critical total=${total} (this ref=${CI_COMMIT_REF_NAME})"
+
+      # Direct push build of an integration branch (not a merge request):
+      # only publish the baseline, do not enforce.
+      case "${CI_COMMIT_REF_NAME}" in
+        ${SAST_BASELINE_GLOB})
+          if [ -z "${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-}" ]; then
+            echo "On integration branch ${CI_COMMIT_REF_NAME}; gate is informational. Not failing."
+            exit 0
+          fi
+          ;;
+      esac
+
+      BASE_REF="${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-${SAST_BASELINE_REF}}"
+      if [ -z "${BASE_REF}" ]; then
+        echo "No baseline ref (not an MR pipeline and SAST_BASELINE_REF unset). Skipping new-only enforcement."
+        exit 0
+      fi
+      echo "baseline ref=${BASE_REF}"
+
+      url="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/jobs/artifacts/${BASE_REF}/raw/gl-sast-report.json?job=semgrep-sast"
+      http=$(curl -s -o baseline.json -w '%{http_code}' --header "JOB-TOKEN: ${CI_JOB_TOKEN}" "${url}" || echo "000")
+      echo "baseline fetch HTTP=${http}"
+
+      if [ "${http}" != "200" ] || ! jq -e . baseline.json >/dev/null 2>&1; then
+        echo "No usable baseline report on ${BASE_REF} (bootstrap). Skipping new-only enforcement."
+        exit 0
+      fi
+
+      jq "${SIG}" baseline.json > base_sigs.json
+      jq --slurpfile base base_sigs.json '
+        [.vulnerabilities[]
+         | select(.severity=="High" or .severity=="Critical")
+         | {severity, name,
+            file: (.location.file // "?"),
+            line: (.location.start_line // 0),
+            sig: (.severity + "|" + ((.identifiers[0].value // "?")|tostring) + "|" + (.location.file // "?"))}]
+        | map(select((.sig) as $s | ($base[0] | index($s)) | not))
+      ' gl-sast-report.json > new_findings.json
+
+      new_count=$(jq 'length' new_findings.json)
+      echo "NEW High/Critical findings=${new_count}"
+      jq -r '.[] | "- [\(.severity)] \(.name) (\(.file):\(.line))"' new_findings.json
+
+      if [ "${new_count}" -gt 0 ]; then
+        echo "New High/Critical SAST findings introduced by this branch. Failing the pipeline."
+        exit 1
+      fi
+      echo "No new High/Critical findings vs baseline. Passing."
+
 pages:
   image: python:3.11
   stage: deploy

.pre-commit-config.yaml

@@ -1,11 +1,11 @@
 repos:
   - repo: https://github.com/pycqa/isort
-    rev: 6.0.1
+    rev: 8.0.1
     hooks:
       - id: isort
 
   - repo: https://github.com/psf/black
-    rev: 25.1.0
+    rev: 26.5.1
     hooks:
       - id: black
         args: [--line-length=99]

CHANGELOG.md

@@ -1,5 +1,68 @@
 # Change log
 
+## [v1.3.0(WIP)+fix/partial-quant-with-rotation-bug] 2026-07-03
+
+### Bug fix
+- Fixed Hadamard online hook registration for rotation + **partial quantization** models. Previously the `down_proj` target layer classes were derived from the recorded `quant_method` (`gptq`/`dbf`/`onebit`), or by sampling the **first** `down_proj` layer's type. When a model is only partially quantized (mixed quantized / unquantized `down_proj` layers) or contains multiple `down_proj` types, hooks were registered on the wrong classes — either missing quantized layers or firing on plain `nn.Linear` — degrading rotated-model inference (`onecomp/quantized_model_loader.py`, `onecomp/runner.py`, `onecomp/pre_process/rotation_utils.py`)
+  - Hadamard hook target types are now derived from the actual model instead of `quant_method`. Added `collect_down_proj_types()` and `collect_quantized_down_proj_types()` to `rotation_utils.py`
+  - `QuantizedModelLoader` (loading from disk) uses `collect_down_proj_types()` to collect **all** distinct `down_proj` layer types from the loaded model, **including** `nn.Linear` when present (e.g. unquantized `down_proj` in a saved partial-quantization model); it intentionally does **not** filter `nn.Linear`
+  - `Runner` hook re-registration (during a quantization run, where some `down_proj` may still be `nn.Linear`) uses `collect_quantized_down_proj_types()`, which **excludes** `nn.Linear` so unquantized `down_proj` layers do not receive hooks; skips registration entirely when no quantized `down_proj` exists
+
+### Test
+- Added regression tests for Hadamard hook target-type collection, pinning `down_proj` type discovery for both full and partial quantization (`tests/onecomp/runner/test_hadamard_hook_type_collection.py`)
+
+## [v1.3.0(WIP)+feature/lora-save-load-vllm-infer_jointq] 2026-06-19 16:45:00
+
+### LoRA Adapter Sidecar Save/Load
+
+- Updated `Runner.save_quantized_model()` to save GPTQ + LoRA SFT outputs in HF/vLLM-compatible form when `LoRAGPTQLinear` modules are present: the base quantized model is saved as normal safetensors, while LoRA weights are written as a PEFT sidecar in `lora_adapter/` (`adapter_model.safetensors`, `adapter_config.json`) (`onecomp/runner.py`)
+  - Uses the in-memory `self.quantized_model` when available, preserving post-process changes; falls back to `create_quantized_model()` only when no quantized model is cached
+  - Flattens `LoRAGPTQLinear.base_layer` tensors back to the base GPTQ key layout, excludes `lora_A` / `lora_B` tensors from base safetensors, and packs GPTQ export tensors when possible without mutating the in-memory model
+  - Saves LoRA adapter tensors in the base model dtype from `model_config.dtype`, avoiding an extra rounding step for bf16 models
+- Updated `QuantizedModelLoader.load_quantized_model()` to auto-detect LoRA sidecars and re-wrap matching layers with `LoRAGPTQLinear` during load for save/load round-trips (`onecomp/quantized_model_loader.py`)
+  - Resolves adapter layers by exact match or `layers.{idx}.*` suffix when module prefixes differ, and fails fast on ambiguous LoRA suffix matches while keeping the first-match behavior for the quantized-layer load path
+  - Raises `ValueError` when not all adapter layers are applied, reporting applied/expected/skipped counts and pointing to the WARNING logs for skipped layer names and reasons
+
+### GPTQ Pack State and Post-Processing
+
+- Updated post-process workflows to keep GPTQ models packed across the Runner boundary: `Runner.run_post_processes()` passes a packed CPU quantized model to post-processors, and `PostProcessLoraSFT` temporarily unpacks GPTQ base layers for training before restoring the incoming pack state (`onecomp/runner.py`, `onecomp/post_process/post_process_lora_sft.py`)
+- Added in-place pack/unpack utilities to `GPTQLinear` (`pack_in_place()`, `unpack_in_place()`) plus a shared `is_packable_wbits()` helper for AutoGPTQ-compatible packed bit-widths (`onecomp/quantizer/gptq/gptq_layer.py`)
+
+### Examples: legacy backups
+
+- Preserved the previous `example/post_process/example_lora_sft.py` workflow as `example/post_process/example_lora_sft_legacy.py`
+- Preserved the previous `example/post_process/example_lora_sft_knowledge.py` workflow as `example/post_process/example_lora_sft_knowledge_legacy.py`
+
+### Examples
+
+- Updated `example/post_process/example_lora_sft.py`: end-to-end GPTQ + LoRA SFT workflow using HF-compatible save/load with a PEFT LoRA adapter sidecar, PPL evaluation, and loaded-model generation check
+- Updated `example/post_process/example_lora_sft_knowledge.py`: knowledge-injection LoRA SFT example using `onecomp_knowledge.jsonl`, including save/load round-trip and output comparison
+- Added `example/post_process/example_lora_sft_knowledge_jointq.py`: JointQ counterpart of the knowledge-injection LoRA SFT workflow
+- Added `example/post_process/example_lora_gptq_vllm_inference.py`: end-to-end GPTQ + LoRA SFT workflow validating vLLM inference with saved LoRA adapters, including GPTQ-only vs GPTQ+LoRA output comparison
+
+### Tests
+
+- Extended LoRA SFT post-process tests with a JointQ smoke test (conditional on JointQ/CUDA availability), packed-in/packed-out behavior, and helper coverage for `LoRAGPTQLinear.base_layer` (`tests/onecomp/post_process/test_post_process_lora_sft.py`)
+- Added `GPTQLinear` pack/unpack in-place tests covering forward-output round-trips, idempotent no-op behavior, and non-packable bit-width handling (`tests/onecomp/quantizer/gptq/test_gptq_layer_pack.py`)
+- Added CPU-only save/load round-trip tests for GPTQ + LoRA SFT and non-LoRA GPTQ paths, including packed base tensors, sidecar output, reload wrapping, and logits preservation (`tests/onecomp/runner/test_lora_save_load_roundtrip.py`)
+- Added `_resolve_name_by_layer_suffix()` tests covering exact, unique suffix, no-match, and ambiguous first/error modes (`tests/onecomp/runner/test_resolve_name_by_layer_suffix.py`)
+- Added CPU-only LoRA adapter sidecar dtype tests covering base-dtype saves, unexpected dtype failures, and PEFT key/config conventions (`tests/onecomp/runner/test_save_lora_adapter_sidecar_dtype.py`)
+
+## [v1.2.0+feature/legacy-vllm] 2026-06-09
+
+### Environment updates
+
+- Added `envs/vllm/` with versioned vLLM environment definitions (`0.12.0`, `0.15.1`).
+
+## [v1.3.0] 2026-MM-DD (WIP)
+
+(TODO: Add changelog for v1.3.0)
+
+### Bug fix
+- Text-only `generate()` on multimodal models (e.g. Gemma-4 12B) could emit modality delimiter tokens and degrade output after quantize→reload, because `load_quantized_model()` did not restore `generation_config.json` (including `suppress_tokens`). Now loads it from the save directory when present (`quantized_model_loader.py`).
+- Fixed VLM (e.g. Gemma3) quantized model save/load: safetensors key prefixes from `save_pretrained` (`model.language_model.model.layers.*`) did not match the `from_config` model (`model.language_model.layers.*`), so `load_state_dict(..., assign=True)` left `qweight` / `scales` / `qzeros` at zero and generation degraded (`onecomp/quantized_model_loader.py`)
+  - Added `_remap_state_dict_keys()` to normalize checkpoint keys before `_replace_quantized_layers`; `_apply_known_state_dict_key_rewrites()` rewrites `.language_model.model.` → `.language_model.` (pattern-based, without requiring keys to exist in the empty model yet)
+
 ## [v1.2.1] 2026-07-03
 
 ### Security

README.md

@@ -274,10 +274,19 @@ uv run mkdocs serve
 
 Then open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.
 
+## 📓 Tutorial Notebook
+
+Interactive walkthrough in Jupyter or [Google Colab](https://colab.research.google.com/github/FujitsuResearch/OneCompression/blob/main/notebook/01_tutorial.ipynb)
+— RTN visualization, `Runner.auto_run`, and vLLM chat inference.
+
+See [`notebook/README.md`](./notebook/README.md) for local setup, or the
+[Tutorial Notebook guide](https://FujitsuResearch.github.io/OneCompression/getting-started/tutorial-notebook/) in the docs.
+
 ## 🚀 Examples
 
 | Category | Script | Description |
 |----------|--------|-------------|
+| Tutorial | [01_tutorial.ipynb](./notebook/01_tutorial.ipynb) | Interactive notebook (Jupyter / Colab) |
 | Quantization | [example_gptq.py](./example/example_gptq.py) | GPTQ quantization |
 | | [example_qep_gptq.py](./example/example_qep_gptq.py) | GPTQ + QEP (error propagation) |
 | | [example_lpcd_gptq.py](./example/example_lpcd_gptq.py) | GPTQ + QEP + LPCD quantization |