Cleanup/repo tidy

.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Hard gates (must pass): ruff, mkdocs build, pytest.
+# Informational (failures are reported but do not block the PR): mypy.
+# The CUDA-only SDPA tests (qat/attention.py use_gqa_in_sdpa / enable_gqa path)
+# are gated behind the `requires_cuda` fixture and skip on the CPU runner, so
+# pytest is green on any box. The mypy debt (68 pre-existing errors) is tracked
+# separately and demoted to informational for now.
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install dev deps
+        run: uv sync --extra dev
+
+      - name: Ruff
+        run: uv run ruff check src tests examples
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install mkdocs-material
+        run: pip install mkdocs-material
+
+      - name: Build the docs site
+        run: mkdocs build --strict
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (all extras except redteam, which needs Python <= 3.12)
+        run: uv sync --extra dev --extra swebench --extra vllm-ptq
+
+      - name: Unit tests
+        run: uv run pytest -q
+
+  types:
+    runs-on: ubuntu-latest
+    continue-on-error: true   # informational: pre-existing mypy debt
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+
+      # `vllm-ptq` (llmcompressor) is imported lazily in vllm_export/ — installing
+      # it lets mypy resolve those imports instead of reporting import-not-found.
+      - name: Install dev + lazy-import deps
+        run: uv sync --extra dev --extra vllm-ptq
+
+      - name: MyPy
+        run: uv run mypy src
+
+  pages:
+    needs: [lint, docs, test]
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install mkdocs-material
+        run: pip install mkdocs-material
+
+      - name: Build the docs site
+        run: mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.gitignore

@@ -9,6 +9,8 @@ build/
 # Workspace artifacts
 workspace/
 out/
+# mkdocs build output (rebuilt by CI on every push to main)
+site/
 *.gguf
 *.kld
 *.imatrix
@@ -42,6 +44,13 @@ datasets/**/data/
 # scripts, and published to the Hub rather than here.
 uploads/
 
+# Experiment workspaces and per-experiment notes are kept locally (the scripts
+# that regenerate them are tracked in scripts/; the published numbers live in
+# the README/docs). Untracked so a fresh clone stays lean.
+experiments/
+docs/runs/
+datasets/t/
+
 # Local clone of the prism llama.cpp fork (LLAMA_CPP_DIR for the Q2_0 ternary export).
 # Fetched separately, like vendor/llama.cpp; not vendored into this repo's history.
 vendor/llama.cpp-prism/

.pre-commit-config.yaml

@@ -0,0 +1,53 @@
+# Pre-commit: auto-fix the cheap, mechanical CI failures before they reach a
+# push. Mirrors the CI hard gates (ruff, pytest) plus git hygiene.
+#
+# Install:  pre-commit install        (or: pre-commit install --install-hooks)
+# Run on everything:  pre-commit run --all-files
+# Bypass in an emergency:  git commit --no-verify
+#
+# Deliberately NOT included:
+#   - `ruff format`: the repo is not yet format-clean (144 files would be
+#     rewritten on first run). Adopt it deliberately once the tree is clean.
+#   - mypy: informational in CI (pre-existing debt); running it on every
+#     commit would just slow the hook down without gating anything.
+#   - pytest: a fast subset runs here as a smoke check, but the authoritative
+#     suite stays on the CI runner (needs the full extras + CUDA skips).
+# Vendored / third-party files stay byte-for-byte as shipped:
+#   - _swerebench_v2_parsers.py is vendored verbatim (MIT) and is ALL-ignored
+#     by ruff; scripts/vendor_swerebench_parsers.py --check compares its content
+#     exactly, so any whitespace "fix" here would register as drift.
+#   - native/jlens_server/vendor/ is third-party code (cpp-httplib).
+# This pre-commit version has no top-level `exclude`, so the same pattern is
+# repeated on each hygiene hook below.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-merge-conflict   # catches leftover <<<<<<< conflict markers
+        exclude: 'src/quant_tuner/eval/_swerebench_v2_parsers\.py|native/jlens_server/vendor/'
+      - id: trailing-whitespace
+        exclude: 'src/quant_tuner/eval/_swerebench_v2_parsers\.py|native/jlens_server/vendor/'
+      - id: end-of-file-fixer
+        exclude: 'src/quant_tuner/eval/_swerebench_v2_parsers\.py|native/jlens_server/vendor/'
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.2
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+        files: ^(src|tests|examples)/
+
+  - repo: local
+    hooks:
+      - id: pytest-smoke
+        name: pytest (fast subset)
+        # Quick catch for the module-level import failures that broke CI
+        # (scripts.* imports). The full suite is the CI job's job; this only
+        # needs to import the modules it touches, so it stays fast.
+        entry: python -m pytest tests/unit -q -x --no-header
+        language: system
+        pass_filenames: false
+        # Only when Python files under tests/src changed.
+        files: ^(src|tests)/
+        verbose: true