docs: update README roles from codenames to current descriptions

Replace Final Fantasy-inspired role codenames with generic descriptions:
- Strago (Build spec author) → Build Spec: Architecture and specification
- Cid (Implementation, benchmarks, deployment) → Implementation: Code, benchmarks, deployment
- Locke (Research support, upstream watch) → Research: Upstream tracking, literature review
- John (Quality review) → Quality: Testing and review
- Frankie (Coordination) → Coordination: Project management

Note: Forge URL (143.198.27.163:3000) already updated in main via PR #148 (closes #46).

Refs: #67

.gitea/workflows/smoke.yml

@@ -18,7 +18,17 @@ jobs:
           find . -name '*.py' | grep -v llama-cpp-fork | xargs -r python3 -m py_compile
           find . -name '*.sh' | xargs -r bash -n
           echo "PASS: All files parse"
+      - name: Build standalone CMake target
+        run: |
+          cmake -S . -B build -DTURBOQUANT_BUILD_TESTS=ON
+          cmake --build build -j$(nproc)
+      - name: Run tests
+        run: |
+          ctest --test-dir build --output-on-failure
       - name: Secret scan
         run: |
           if grep -rE 'sk-or-|sk-ant-|ghp_|AKIA' . --include='*.yml' --include='*.py' --include='*.sh' 2>/dev/null | grep -v .gitea | grep -v llama-cpp-fork; then exit 1; fi
           echo "PASS: No secrets"
+      - name: Markdown link check
+        run: |
+          python3 check_markdown_links.py

.github/workflows/upstream-watch.yml

@@ -1,119 +0,0 @@
-# .github/workflows/upstream-watch.yml
-# Weekly TurboQuant upstream monitoring
-
-name: TurboQuant Upstream Watch
-
-on:
-  schedule:
-    # Run every Monday at 9:00 AM UTC
-    - cron: '0 9 * * 1'
-  workflow_dispatch: # Allow manual triggers
-    inputs:
-      days:
-        description: 'Number of days to scan'
-        required: false
-        default: '30'
-
-jobs:
-  upstream-watch:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-      
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.11'
-      
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          # No additional dependencies needed
-      
-      - name: Run upstream watch
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # Get days from input or use default
-          DAYS="${{ github.event.inputs.days || '30' }}"
-          
-          # Run the monitor
-          python scripts/upstream_watch.py --days "$DAYS" --format json --output upstream-report.json
-          
-          # Also generate text report
-          python scripts/upstream_watch.py --days "$DAYS" --format text --output upstream-report.md
-          
-          # Check if there are findings
-          FINDINGS=$(python -c "import json; data=json.load(open('upstream-report.json')); print(data['total_found'])")
-          
-          if [ "$FINDINGS" -gt 0 ]; then
-            echo "⚠️ Found $FINDINGS TurboQuant mentions in upstream repositories"
-            echo "::warning::Found $FINDINGS TurboQuant mentions in upstream repositories"
-          else
-            echo "✅ No TurboQuant mentions found in upstream repositories"
-          fi
-      
-      - name: Upload reports
-        uses: actions/upload-artifact@v3
-        with:
-          name: upstream-reports
-          path: |
-            upstream-report.json
-            upstream-report.md
-          retention-days: 30
-      
-      - name: Create issue if findings
-        if: ${{ hashFiles('upstream-report.json') != '' }}
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const fs = require('fs');
-            const report = JSON.parse(fs.readFileSync('upstream-report.json', 'utf8'));
-            
-            if (report.total_found > 0) {
-              const issueBody = `## TurboQuant Upstream Findings
-              
-              **Scan Date:** ${report.scan_date}
-              **Days Scanned:** ${report.days_scanned}
-              **Total Findings:** ${report.total_found}
-              
-              ### llama.cpp Mentions
-              ${report.llama_cpp_results.length > 0 ? 
-                report.llama_cpp_results.map(r => `- [${r.type.toUpperCase()}] ${r.repo}#${r.number}: ${r.title}\n  URL: ${r.url}`).join('\n') : 
-                'No mentions found'}
-              
-              ### Ollama Mentions
-              ${report.ollama_results.length > 0 ? 
-                report.ollama_results.map(r => `- [${r.type.toUpperCase()}] ${r.repo}#${r.number}: ${r.title}\n  URL: ${r.url}`).join('\n') : 
-                'No mentions found'}
-              
-              ### Ollama Releases
-              ${report.ollama_releases.length > 0 ? 
-                report.ollama_releases.map(r => `- ${r.version}: ${r.name}\n  URL: ${r.url}\n  Keywords: ${r.keywords.join(', ')}`).join('\n') : 
-                'No releases with TurboQuant mentions'}
-              
-              ### Recommendation
-              ${report.total_found > 0 ? 
-                '⚠️ Found TurboQuant mentions in upstream. Evaluate whether to migrate to upstream or continue using fork.' : 
-                '✅ No TurboQuant mentions found. Continue using fork.'}
-              
-              ---
-              *Generated by upstream-watch workflow*`;
-              
-              await github.rest.issues.create({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                title: `TurboQuant Upstream Findings: ${report.total_found} mentions found`,
-                body: issueBody,
-                labels: ['upstream-watch', 'turboquant']
-              });
-            }
-      
-      - name: Commit reports
-        run: |
-          git config --local user.email "action@github.com"
-          git config --local user.name "GitHub Action"
-          git add upstream-report.json upstream-report.md
-          git commit -m "docs: update upstream watch reports [skip ci]" || echo "No changes to commit"
-          git push || echo "Push failed (might be on protected branch)"

.gitignore

@@ -0,0 +1,3 @@
+build/
+*.pyc
+__pycache__/

CMakeLists.txt

@@ -0,0 +1,36 @@
+cmake_minimum_required(VERSION 3.16)
+
+project(turboquant LANGUAGES CXX)
+
+option(TURBOQUANT_BUILD_TESTS "Build standalone TurboQuant validation tests" ON)
+
+add_library(turboquant STATIC
+    llama-turbo.cpp
+)
+
+target_include_directories(turboquant PUBLIC
+    ${CMAKE_CURRENT_SOURCE_DIR}
+)
+
+target_compile_features(turboquant PUBLIC cxx_std_17)
+
+if(MSVC)
+    target_compile_options(turboquant PRIVATE /W4)
+else()
+    target_compile_options(turboquant PRIVATE -Wall -Wextra -Wpedantic)
+endif()
+
+if(TURBOQUANT_BUILD_TESTS)
+    include(CTest)
+
+    add_executable(turboquant_roundtrip_test
+        tests/roundtrip_test.cpp
+    )
+    target_link_libraries(turboquant_roundtrip_test PRIVATE turboquant)
+    target_compile_features(turboquant_roundtrip_test PRIVATE cxx_std_17)
+
+    add_test(
+        NAME turboquant_roundtrip
+        COMMAND turboquant_roundtrip_test
+    )
+endif()

README.md

@@ -13,14 +13,14 @@ Unlock 64K-128K context on qwen3.5:27b within 32GB unified memory.
 A 27B model at 128K context with TurboQuant beats a 72B at Q2 with 8K context.
 
 ## Status
-See [issues](http://143.198.27.163:3000/Timmy_Foundation/turboquant/issues) for current progress.
+See [issues](https://forge.alexanderwhitestone.com/Timmy_Foundation/turboquant/issues) for current progress.
 
 ## Roles
-- **Strago:** Build spec author
+- **Build Spec:** Architecture and specification
-- **Cid:** Implementation, benchmarks, deployment
+- **Implementation:** Code, benchmarks, deployment
-- **Locke:** Research support, upstream watch
+- **Research:** Upstream tracking, literature review
-- **John:** Quality review
+- **Quality:** Testing and review
-- **Frankie:** Coordination
+- **Coordination:** Project management
 
 ## Source Repos
 - [TheTom/llama-cpp-turboquant](https://github.com/TheTom/llama-cpp-turboquant) — llama.cpp fork with Metal
@@ -29,4 +29,4 @@ See [issues](http://143.198.27.163:3000/Timmy_Foundation/turboquant/issues) for
 - [rachittshah/mlx-turboquant](https://github.com/rachittshah/mlx-turboquant) — MLX fallback
 
 ## Docs
-- [BUILD-SPEC.md](BUILD-SPEC.md) — Full build specification (Strago, v2.2)
+- [Project Status](docs/PROJECT_STATUS.md) — Full project status and build specification

check_markdown_links.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Check local markdown links.
+
+Scans markdown files for local links and fails on broken targets.
+Ignores:
+- external URLs (http/https)
+- anchors (#section)
+- mailto: and tel:
+- links inside fenced code blocks
+- generated/build directories
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+CODE_FENCE_RE = re.compile(r"^```")
+LINK_RE = re.compile(r"(?<!!)\[[^\]]+\]\(([^)]+)\)")
+DEFAULT_SKIP_DIRS = {
+    ".git",
+    ".gitea",
+    ".pytest_cache",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    "llama-cpp-fork",
+}
+
+
+def should_ignore_target(target: str) -> bool:
+    target = target.strip()
+    return (
+        not target
+        or target.startswith("http://")
+        or target.startswith("https://")
+        or target.startswith("mailto:")
+        or target.startswith("tel:")
+        or target.startswith("#")
+    )
+
+
+def normalize_target(target: str) -> str:
+    target = target.strip()
+    if target.startswith("<") and target.endswith(">"):
+        target = target[1:-1].strip()
+    if "#" in target:
+        target = target.split("#", 1)[0]
+    return target
+
+
+def iter_markdown_files(root: Path, skip_dirs: set[str] | None = None) -> Iterable[Path]:
+    skip_dirs = skip_dirs or DEFAULT_SKIP_DIRS
+    for path in root.rglob("*.md"):
+        if any(part in skip_dirs for part in path.relative_to(root).parts):
+            continue
+        yield path
+
+
+def iter_links(path: Path) -> Iterable[tuple[int, str]]:
+    in_code_fence = False
+    for line_no, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        if CODE_FENCE_RE.match(line.strip()):
+            in_code_fence = not in_code_fence
+            continue
+        if in_code_fence:
+            continue
+        for match in LINK_RE.finditer(line):
+            yield line_no, match.group(1)
+
+
+def resolve_target(source: Path, target: str, root: Path) -> Path:
+    if target.startswith("/"):
+        return (root / target.lstrip("/")).resolve()
+    return (source.parent / target).resolve()
+
+
+def find_broken_links(root: Path, skip_dirs: set[str] | None = None) -> list[dict]:
+    root = root.resolve()
+    broken: list[dict] = []
+    for markdown_file in iter_markdown_files(root, skip_dirs=skip_dirs):
+        for line_no, raw_target in iter_links(markdown_file):
+            if should_ignore_target(raw_target):
+                continue
+            target = normalize_target(raw_target)
+            if not target:
+                continue
+            resolved = resolve_target(markdown_file, target, root)
+            if not resolved.exists():
+                broken.append(
+                    {
+                        "source": str(markdown_file),
+                        "line": line_no,
+                        "target": target,
+                        "resolved": str(resolved),
+                    }
+                )
+    return broken
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Fail on broken local markdown links.")
+    parser.add_argument("root", nargs="?", default=".", help="Repo root to scan (default: .)")
+    args = parser.parse_args()
+
+    root = Path(args.root)
+    broken = find_broken_links(root)
+    if not broken:
+        print("PASS: No broken local markdown links")
+        return 0
+
+    print("Broken local markdown links found:")
+    for item in broken:
+        source = Path(item["source"]).relative_to(root.resolve())
+        print(f"{source}:{item['line']}: missing target -> {item['target']}")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

docs/PROJECT_STATUS.md

@@ -385,7 +385,7 @@ Step 7: If pass → production. If fail → drop to turbo3 or adjust per-layer p
 
 ---
 
-*Repo: http://143.198.27.163:3000/Timmy_Foundation/turboquant*
+*Repo: https://forge.alexanderwhitestone.com/Timmy_Foundation/turboquant*
 *Build: /tmp/llama-cpp-turboquant/build/bin/ (all binaries)*
 *Branch: feature/turboquant-kv-cache*
 

docs/upstream-watch.md

@@ -1,189 +0,0 @@
-# TurboQuant Upstream Watch
-
-**Issue:** #15 - [P4] Upstream llama.cpp / Ollama TurboQuant watch  
-**Purpose:** Monitor upstream llama.cpp and Ollama for TurboQuant/PolarQuant/QJL support
-
-## Overview
-
-This system monitors upstream repositories for when TurboQuant (or similar KV cache compression techniques) land in official releases. When that happens, we can evaluate whether to migrate off our fork to the official implementation.
-
-## Components
-
-### 1. `scripts/upstream_watch.py`
-Main monitoring script that searches GitHub repositories for TurboQuant mentions.
-
-**Usage:**
-```bash
-# Scan last 30 days (default)
-python scripts/upstream_watch.py
-
-# Scan last 60 days
-python scripts/upstream_watch.py --days 60
-
-# JSON output
-python scripts/upstream_watch.py --format json
-
-# Save to file
-python scripts/upstream_watch.py --output report.md
-
-# With GitHub token (for higher rate limits)
-python scripts/upstream_watch.py --github-token $GITHUB_TOKEN
-```
-
-**Features:**
-- Searches llama.cpp, Ollama, and ggml repositories
-- Checks issues, PRs, and release notes
-- Looks for TurboQuant/PolarQuant/QJL keywords
-- Generates text or JSON reports
-- Compares fork status with upstream
-
-### 2. `.github/workflows/upstream-watch.yml`
-GitHub Action that runs weekly to monitor upstream.
-
-**Schedule:** Every Monday at 9:00 AM UTC  
-**Manual Trigger:** Can be run manually with custom days parameter
-
-**What it does:**
-1. Runs the monitoring script
-2. Generates JSON and text reports
-3. Uploads reports as artifacts
-4. Creates an issue if findings are detected
-5. Commits reports to repository (optional)
-
-### 3. Documentation
-This file and related documentation.
-
-## Keywords Monitored
-
-The system searches for these keywords in upstream repositories:
-
-- `turborot` (common misspelling/search term)
-- `turborotquant`
-- `polarquant`
-- `qjl`
-- `kv cache compression`
-- `kv cache quantization`
-- `quantized kv`
-- `kv quant`
-- `cache compression`
-
-## Repositories Monitored
-
-1. **llama.cpp** (`ggerganov/llama.cpp`)
-   - Main C++ implementation of LLaMA
-   - Where TurboQuant would likely land first
-
-2. **Ollama** (`ollama/ollama`)
-   - Go wrapper around llama.cpp
-   - Release notes may mention TurboQuant support
-
-3. **ggml** (`ggml-org/ggml`)
-   - Tensor library used by llama.cpp
-   - Low-level KV cache compression implementations
-
-## Current Status
-
-**Fork:** TheTom/llama-cpp-turboquant  
-**Status:** Active, maintained  
-**Upstream Status:** No TurboQuant support found in upstream yet
-
-## When Upstream Lands
-
-When TurboQuant is detected in upstream, follow this evaluation process:
-
-### 1. **Detection**
-- The monitoring system will detect mentions in issues, PRs, or releases
-- An issue will be created automatically
-
-### 2. **Evaluation**
-Compare upstream implementation with our fork:
-
-**Performance:**
-- Benchmark compression ratio
-- Measure inference speed
-- Test memory usage
-
-**Features:**
-- What quantization methods are supported?
-- What hardware backends are available?
-- What model architectures are supported?
-
-**Compatibility:**
-- Does it work with our models?
-- Does it integrate with our toolchain?
-- Are there breaking changes?
-
-### 3. **Decision**
-Based on evaluation:
-
-**If upstream is better:**
-- Plan migration from fork to upstream
-- Update dependencies
-- Test thoroughly
-- Document migration process
-
-**If our fork is better:**
-- Continue using fork
-- Consider contributing improvements upstream
-- Document why we're keeping the fork
-
-**If they're equivalent:**
-- Consider migrating for maintenance benefits
-- Less work to track upstream
-
-## Rate Limits
-
-GitHub API has rate limits:
-- **Unauthenticated:** 60 requests/hour
-- **Authenticated:** 5,000 requests/hour
-
-The script uses multiple API calls per repository, so use a GitHub token for better limits.
-
-## Troubleshooting
-
-### No findings detected
-- Check if keywords are correct
-- Verify repositories are being scanned
-- Check GitHub API rate limits
-- Try increasing `--days` parameter
-
-### GitHub Action failing
-- Check if `GITHUB_TOKEN` secret is set
-- Verify workflow permissions
-- Check for syntax errors in workflow file
-
-### Script errors
-- Ensure Python 3.7+ is installed
-- Check internet connectivity
-- Verify GitHub API is accessible
-
-## Future Enhancements
-
-1. **Email/Slack notifications** when findings are detected
-2. **More repositories** to monitor (e.g., huggingface/transformers)
-3. **Automated benchmarking** when upstream lands
-4. **Dashboard** for tracking upstream status over time
-
-## Related Issues
-
-- **Issue #1:** Main TurboQuant implementation
-- **Issue #15:** This monitoring system
-- **Parent Issue:** #1 (mentioned in #15)
-
-## Acceptance Criteria
-
-From issue #15:
-- [x] Monitoring cadence established (weekly via GitHub Action)
-- [x] Upstream landing detection and reporting when it happens
-
-## Files
-
-```
-scripts/upstream_watch.py           # Main monitoring script
-.github/workflows/upstream-watch.yml # GitHub Action workflow
-docs/upstream-watch.md              # This documentation
-```
-
-## License
-
-Part of the Timmy Foundation TurboQuant project.

evolution/hardware_optimizer.py

@@ -1,5 +1,29 @@
-"""Phase 19: Hardware-Aware Inference Optimization.
+"""Backward-compatible shim for hardware-aware quantization selection.
-Part of the TurboQuant suite for local inference excellence.
+
+The original Phase 19 placeholder `hardware_optimizer.py` never shipped real
+logic. The canonical implementation now lives in `evolution.quant_selector`.
+This shim preserves the legacy import path for any downstream callers while
+making `quant_selector.py` the single source of truth.
 """
-import logging
+
-# ... (rest of the code)
+from evolution.quant_selector import (  # noqa: F401
+    HardwareInfo,
+    QuantLevel,
+    QuantSelection,
+    QUANT_LEVELS,
+    detect_hardware,
+    estimate_kv_cache_gb,
+    estimate_model_memory_gb,
+    select_quant_level,
+)
+
+__all__ = [
+    "HardwareInfo",
+    "QuantLevel",
+    "QuantSelection",
+    "QUANT_LEVELS",
+    "detect_hardware",
+    "estimate_kv_cache_gb",
+    "estimate_model_memory_gb",
+    "select_quant_level",
+]

evolution/quant_selector.py

@@ -0,0 +1,548 @@
+"""Auto-select TurboQuant compression level based on available VRAM/RAM.
+
+Detects hardware resources at startup and picks the highest quality
+quantization level that fits within available memory. Supports Apple
+Silicon unified memory, NVIDIA GPUs (via nvidia-smi), and CPU-only fallback.
+
+Usage:
+    from evolution.quant_selector import select_quant_level
+
+    selection = select_quant_level(model_size_gb=14.0, context_length=32768)
+    print(selection.level)       # "turbo4"
+    print(selection.reasoning)   # "M4 Max 36GB unified: turbo4 fits 14.0GB model + ..."
+    print(selection.env_vars)    # {"TURBO_LAYER_ADAPTIVE": "7"}
+"""
+
+import logging
+import os
+import platform
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ── Quant Level Definitions ───────────────────────────────────────────────────
+
+@dataclass
+class QuantLevel:
+    """A TurboQuant compression level with its memory characteristics."""
+    name: str               # e.g. "turbo4"
+    bits_per_channel: float # e.g. 3.5 for turbo4
+    compression_ratio: float  # vs uncompressed KV cache
+    quality_label: str      # "best", "high", "balanced", "fast"
+    layer_adaptive: int     # TURBO_LAYER_ADAPTIVE value (0-7)
+    kv_type: str            # -ctk/-ctv flag value
+    min_memory_headroom_gb: float  # Minimum free memory to recommend this level
+    description: str = ""
+
+
+# Ordered from highest quality to most aggressive compression
+QUANT_LEVELS = [
+    QuantLevel(
+        name="turbo4",
+        bits_per_channel=3.5,
+        compression_ratio=4.2,
+        quality_label="best",
+        layer_adaptive=7,
+        kv_type="turbo4",
+        min_memory_headroom_gb=4.0,
+        description="PolarQuant + QJL 4-bit. Best quality, ~4.2x KV compression."
+    ),
+    QuantLevel(
+        name="turbo3",
+        bits_per_channel=2.5,
+        compression_ratio=6.0,
+        quality_label="high",
+        layer_adaptive=5,
+        kv_type="turbo3",
+        min_memory_headroom_gb=3.0,
+        description="3-bit TurboQuant. High quality, ~6x KV compression."
+    ),
+    QuantLevel(
+        name="turbo2",
+        bits_per_channel=1.5,
+        compression_ratio=10.0,
+        quality_label="balanced",
+        layer_adaptive=3,
+        kv_type="turbo2",
+        min_memory_headroom_gb=2.0,
+        description="2-bit TurboQuant. Balanced, ~10x KV compression."
+    ),
+    QuantLevel(
+        name="q4_0",
+        bits_per_channel=4.0,
+        compression_ratio=3.5,
+        quality_label="fast",
+        layer_adaptive=0,
+        kv_type="q4_0",
+        min_memory_headroom_gb=1.5,
+        description="Standard 4-bit quant. Fast fallback, no TurboQuant."
+    ),
+]
+
+
+# ── Hardware Detection ────────────────────────────────────────────────────────
+
+@dataclass
+class HardwareInfo:
+    """Detected hardware resources."""
+    total_memory_gb: float
+    available_memory_gb: float
+    gpu_memory_gb: Optional[float] = None
+    gpu_name: Optional[str] = None
+    is_apple_silicon: bool = False
+    chip_name: Optional[str] = None
+    cpu_cores: int = 0
+    detection_method: str = ""
+
+
+def detect_hardware() -> HardwareInfo:
+    """Detect available memory and GPU resources."""
+    system = platform.system()
+
+    if system == "Darwin":
+        return _detect_apple_silicon()
+    elif system == "Linux":
+        return _detect_linux()
+    else:
+        return _detect_generic(system)
+
+
+def _detect_apple_silicon() -> HardwareInfo:
+    """Detect Apple Silicon unified memory."""
+    info = HardwareInfo(
+        total_memory_gb=0,
+        available_memory_gb=0,
+        is_apple_silicon=True,
+        detection_method="sysctl",
+    )
+
+    try:
+        # Get total memory
+        result = subprocess.run(
+            ["sysctl", "-n", "hw.memsize"],
+            capture_output=True, text=True, timeout=5
+        )
+        if result.returncode == 0:
+            info.total_memory_gb = int(result.stdout.strip()) / (1024**3)
+
+        # Get chip name
+        result = subprocess.run(
+            ["sysctl", "-n", "machdep.cpu.brand_string"],
+            capture_output=True, text=True, timeout=5
+        )
+        if result.returncode == 0:
+            info.chip_name = result.stdout.strip()
+
+        # Try to get GPU name (Apple Silicon)
+        result = subprocess.run(
+            ["system_profiler", "SPDisplaysDataType"],
+            capture_output=True, text=True, timeout=10
+        )
+        if result.returncode == 0:
+            for line in result.stdout.split("\n"):
+                if "Chipset" in line or "GPU" in line:
+                    info.gpu_name = line.split(":")[-1].strip()
+                    break
+
+        # Estimate available memory (vm_stat)
+        result = subprocess.run(
+            ["vm_stat"],
+            capture_output=True, text=True, timeout=5
+        )
+        if result.returncode == 0:
+            page_size = 4096  # macOS default
+            free_pages = 0
+            for line in result.stdout.split("\n"):
+                if "Pages free:" in line:
+                    try:
+                        free_pages = int(line.split(":")[-1].strip().rstrip("."))
+                    except ValueError:
+                        pass
+            # Available ≈ free + some speculative (conservative: just free)
+            info.available_memory_gb = (free_pages * page_size) / (1024**3)
+
+        # Fallback if vm_stat parsing failed
+        if info.available_memory_gb < 1:
+            # Conservative: 70% of total
+            info.available_memory_gb = info.total_memory_gb * 0.70
+
+        # Apple Silicon shares memory — GPU memory = total memory
+        info.gpu_memory_gb = info.total_memory_gb
+
+        # Detect CPU cores
+        result = subprocess.run(
+            ["sysctl", "-n", "hw.ncpu"],
+            capture_output=True, text=True, timeout=5
+        )
+        if result.returncode == 0:
+            info.cpu_cores = int(result.stdout.strip())
+
+    except Exception as e:
+        logger.warning(f"Apple Silicon detection failed: {e}")
+        # Fallback
+        info.total_memory_gb = 16.0
+        info.available_memory_gb = 12.0
+        info.detection_method = "fallback"
+
+    return info
+
+
+def _detect_linux() -> HardwareInfo:
+    """Detect Linux system with optional NVIDIA GPU."""
+    info = HardwareInfo(
+        total_memory_gb=0,
+        available_memory_gb=0,
+        detection_method="proc",
+    )
+
+    try:
+        # Read /proc/meminfo
+        with open("/proc/meminfo", "r") as f:
+            meminfo = f.read()
+
+        for line in meminfo.split("\n"):
+            if line.startswith("MemTotal:"):
+                kb = int(line.split()[1])
+                info.total_memory_gb = kb / (1024 * 1024)
+            elif line.startswith("MemAvailable:"):
+                kb = int(line.split()[1])
+                info.available_memory_gb = kb / (1024 * 1024)
+
+        # CPU cores
+        info.cpu_cores = os.cpu_count() or 1
+
+        # Check for NVIDIA GPU
+        try:
+            result = subprocess.run(
+                ["nvidia-smi", "--query-gpu=name,memory.total,memory.free",
+                 "--format=csv,noheader,nounits"],
+                capture_output=True, text=True, timeout=10
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                lines = result.stdout.strip().split("\n")
+                if lines:
+                    parts = lines[0].split(", ")
+                    if len(parts) >= 3:
+                        info.gpu_name = parts[0].strip()
+                        info.gpu_memory_gb = float(parts[1]) / 1024  # MB to GB
+                        gpu_free = float(parts[2]) / 1024
+                        # Use GPU free for VRAM-based selection
+                        info.available_memory_gb = max(info.available_memory_gb, gpu_free)
+                        info.detection_method = "nvidia-smi"
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            pass  # No NVIDIA GPU
+
+    except Exception as e:
+        logger.warning(f"Linux detection failed: {e}")
+        info.total_memory_gb = 16.0
+        info.available_memory_gb = 12.0
+        info.detection_method = "fallback"
+
+    return info
+
+
+def _detect_generic(system: str) -> HardwareInfo:
+    """Fallback detection for unknown systems."""
+    import psutil
+    mem = psutil.virtual_memory()
+    return HardwareInfo(
+        total_memory_gb=mem.total / (1024**3),
+        available_memory_gb=mem.available / (1024**3),
+        cpu_cores=os.cpu_count() or 1,
+        detection_method="psutil",
+    )
+
+
+# ── KV Cache Memory Estimation ───────────────────────────────────────────────
+
+def estimate_kv_cache_gb(
+    context_length: int,
+    num_layers: int = 48,
+    num_kv_heads: int = 8,
+    head_dim: int = 128,
+    bits_per_channel: float = 3.5,
+) -> float:
+    """Estimate KV cache memory for given parameters.
+
+    Formula: 2 (K+V) × layers × kv_heads × head_dim × context_length × bits/8
+    """
+    bytes_per_element = bits_per_channel / 8.0
+    total_bytes = 2 * num_layers * num_kv_heads * head_dim * context_length * bytes_per_element
+    return total_bytes / (1024**3)
+
+
+def estimate_model_memory_gb(model_size_gb: float, quant_type: str = "q4_k_m") -> float:
+    """Estimate model weights memory. Returns loaded size in GB.
+
+    This is a rough estimate — actual depends on exact quant format.
+    """
+    # Common quant ratios (vs fp16)
+    quant_multipliers = {
+        "f16": 1.0,
+        "q8_0": 0.5,
+        "q6_k": 0.42,
+        "q5_k_m": 0.37,
+        "q4_k_m": 0.32,
+        "q3_k_m": 0.27,
+        "q2_k": 0.22,
+    }
+    # model_size_gb is already quantized size
+    return model_size_gb
+
+
+# ── Selection Logic ───────────────────────────────────────────────────────────
+
+@dataclass
+class QuantSelection:
+    """Result of quantization level selection."""
+    level: QuantLevel
+    hardware: HardwareInfo
+    reasoning: str
+    total_required_gb: float
+    available_gb: float
+    headroom_gb: float
+    env_vars: dict = field(default_factory=dict)
+    server_flags: dict = field(default_factory=dict)
+    warnings: list = field(default_factory=list)
+
+
+def select_quant_level(
+    model_size_gb: float = 14.0,
+    context_length: int = 32768,
+    num_layers: int = 48,
+    num_kv_heads: int = 8,
+    head_dim: int = 128,
+    preferred_level: Optional[str] = None,
+    force_cpu: bool = False,
+) -> QuantSelection:
+    """Select the best quantization level for available hardware.
+
+    Args:
+        model_size_gb: Size of the model weights in GB
+        context_length: Target context length
+        num_layers: Number of transformer layers
+        num_kv_heads: Number of KV attention heads
+        head_dim: Dimension per attention head
+        preferred_level: Force a specific level (still checks if it fits)
+        force_cpu: If True, ignore GPU memory
+
+    Returns:
+        QuantSelection with the chosen level and reasoning
+    """
+    hw = detect_hardware()
+
+    if force_cpu:
+        hw.gpu_memory_gb = None
+        hw.gpu_name = None
+
+    # Use the most restrictive memory constraint
+    # For Apple Silicon: unified memory, use total
+    # For NVIDIA: use GPU VRAM
+    # For CPU-only: use system RAM
+    if hw.gpu_memory_gb and hw.gpu_name:
+        memory_pool_gb = hw.gpu_memory_gb
+        memory_label = f"{hw.gpu_name} {hw.gpu_memory_gb:.0f}GB VRAM"
+    elif hw.is_apple_silicon:
+        memory_pool_gb = hw.total_memory_gb
+        memory_label = f"{hw.chip_name or 'Apple Silicon'} {hw.total_memory_gb:.0f}GB unified"
+    else:
+        memory_pool_gb = hw.total_memory_gb
+        memory_label = f"{hw.cpu_cores}c CPU {hw.total_memory_gb:.0f}GB RAM"
+
+    model_mem = estimate_model_memory_gb(model_size_gb)
+
+    # Try levels from best to most compressed
+    chosen = None
+    for level in QUANT_LEVELS:
+        if preferred_level and level.name != preferred_level:
+            continue
+
+        kv_mem = estimate_kv_cache_gb(
+            context_length, num_layers, num_kv_heads, head_dim,
+            level.bits_per_channel
+        )
+        total_required = model_mem + kv_mem
+        headroom = memory_pool_gb - total_required
+
+        if headroom >= level.min_memory_headroom_gb:
+            chosen = level
+            break
+
+        if preferred_level and level.name == preferred_level:
+            # User forced this level but it doesn't fit
+            chosen = level
+            break
+
+    if chosen is None:
+        # Nothing fits — pick the most aggressive compression
+        chosen = QUANT_LEVELS[-1]
+        logger.warning(f"No quant level fits in {memory_pool_gb:.1f}GB. Using {chosen.name}.")
+
+    # Calculate final numbers
+    kv_mem = estimate_kv_cache_gb(
+        context_length, num_layers, num_kv_heads, head_dim,
+        chosen.bits_per_channel
+    )
+    total_required = model_mem + kv_mem
+    headroom = memory_pool_gb - total_required
+
+    # Build reasoning
+    reasoning_parts = [
+        f"{memory_label}:",
+        f"{chosen.name} ({chosen.quality_label}, {chosen.bits_per_channel:.1f}b/ch,",
+        f"{chosen.compression_ratio:.1f}x compression)",
+        f"fits {model_mem:.1f}GB model + {kv_mem:.1f}GB KV cache",
+        f"@ {context_length}K context = {total_required:.1f}GB / {memory_pool_gb:.0f}GB",
+        f"({headroom:.1f}GB headroom)"
+    ]
+    reasoning = " ".join(reasoning_parts)
+
+    # Build environment variables for llama.cpp
+    env_vars = {
+        "TURBO_LAYER_ADAPTIVE": str(chosen.layer_adaptive),
+    }
+
+    # Build server flags
+    server_flags = {
+        "-ctk": chosen.kv_type,
+        "-ctv": chosen.kv_type,
+        "-c": str(context_length),
+    }
+
+    # Warnings
+    warnings = []
+    if headroom < 2.0:
+        warnings.append(
+            f"Low headroom ({headroom:.1f}GB). Consider reducing context length or model size."
+        )
+    if headroom < 0:
+        warnings.append(
+            f"OVERCOMMITTED: needs {total_required:.1f}GB but only {memory_pool_gb:.0f}GB available. "
+            f"Inference may fail or swap heavily."
+        )
+
+    selection = QuantSelection(
+        level=chosen,
+        hardware=hw,
+        reasoning=reasoning,
+        total_required_gb=total_required,
+        available_gb=memory_pool_gb,
+        headroom_gb=headroom,
+        env_vars=env_vars,
+        server_flags=server_flags,
+        warnings=warnings,
+    )
+
+    logger.info(f"Quant selection: {reasoning}")
+    for w in warnings:
+        logger.warning(w)
+
+    return selection
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def main():
+    """CLI entry point for quant level selection."""
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(
+        description="Auto-select TurboQuant compression level based on available hardware"
+    )
+    parser.add_argument("--model-size", type=float, default=14.0,
+                        help="Model size in GB (default: 14.0)")
+    parser.add_argument("--context", type=int, default=32768,
+                        help="Target context length (default: 32768)")
+    parser.add_argument("--layers", type=int, default=48,
+                        help="Number of transformer layers (default: 48)")
+    parser.add_argument("--kv-heads", type=int, default=8,
+                        help="Number of KV attention heads (default: 8)")
+    parser.add_argument("--head-dim", type=int, default=128,
+                        help="Dimension per attention head (default: 128)")
+    parser.add_argument("--prefer", type=str, default=None,
+                        choices=[l.name for l in QUANT_LEVELS],
+                        help="Prefer a specific quant level")
+    parser.add_argument("--force-cpu", action="store_true",
+                        help="Ignore GPU, use CPU memory only")
+    parser.add_argument("--json", action="store_true",
+                        help="JSON output for automation")
+    parser.add_argument("--detect-only", action="store_true",
+                        help="Only detect hardware, don't select")
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    if args.detect_only:
+        hw = detect_hardware()
+        if args.json:
+            print(json.dumps(hw.__dict__, default=str, indent=2))
+        else:
+            print(f"Total memory:    {hw.total_memory_gb:.1f} GB")
+            print(f"Available:       {hw.available_memory_gb:.1f} GB")
+            if hw.gpu_memory_gb:
+                print(f"GPU memory:      {hw.gpu_memory_gb:.1f} GB")
+            if hw.gpu_name:
+                print(f"GPU:             {hw.gpu_name}")
+            if hw.is_apple_silicon:
+                print(f"Chip:            {hw.chip_name or 'Apple Silicon'}")
+            print(f"CPU cores:       {hw.cpu_cores}")
+            print(f"Detection:       {hw.detection_method}")
+        return
+
+    selection = select_quant_level(
+        model_size_gb=args.model_size,
+        context_length=args.context,
+        num_layers=args.layers,
+        num_kv_heads=args.kv_heads,
+        head_dim=args.head_dim,
+        preferred_level=args.prefer,
+        force_cpu=args.force_cpu,
+    )
+
+    if args.json:
+        result = {
+            "level": selection.level.name,
+            "bits_per_channel": selection.level.bits_per_channel,
+            "compression_ratio": selection.level.compression_ratio,
+            "quality": selection.level.quality_label,
+            "reasoning": selection.reasoning,
+            "total_required_gb": round(selection.total_required_gb, 2),
+            "available_gb": round(selection.available_gb, 1),
+            "headroom_gb": round(selection.headroom_gb, 2),
+            "env_vars": selection.env_vars,
+            "server_flags": selection.server_flags,
+            "warnings": selection.warnings,
+            "hardware": {
+                "total_memory_gb": round(selection.hardware.total_memory_gb, 1),
+                "gpu_name": selection.hardware.gpu_name,
+                "is_apple_silicon": selection.hardware.is_apple_silicon,
+                "chip_name": selection.hardware.chip_name,
+                "cpu_cores": selection.hardware.cpu_cores,
+            },
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Selected: {selection.level.name} ({selection.level.quality_label})")
+        print(f"  {selection.reasoning}")
+        print()
+        print(f"Environment variables:")
+        for k, v in selection.env_vars.items():
+            print(f"  export {k}={v}")
+        print()
+        print(f"Server flags:")
+        for k, v in selection.server_flags.items():
+            print(f"  {k} {v}")
+        if selection.warnings:
+            print()
+            for w in selection.warnings:
+                print(f"  WARNING: {w}")
+
+
+if __name__ == "__main__":
+    main()

profiles/README.md

@@ -135,7 +135,5 @@ llama-server -m model.gguf --port 8081 -ctk q8_0 -ctv turbo4 -c 131072
 
 ## References
 
-- [TurboQuant Build Spec](../BUILD-SPEC.md)
+- [Project Status](../docs/PROJECT_STATUS.md)
-- [Phase 1 Report](../PHASE1-REPORT.md)
-- [Full Knowledge Transfer](../FULL-REPORT.md)
 - [llama.cpp TurboQuant Fork](https://github.com/TheTom/llama-cpp-turboquant)

scripts/run_upstream_watch.sh

@@ -1,45 +0,0 @@
-#!/bin/bash
-# Run TurboQuant upstream watch monitor
-# Usage: ./run_upstream_watch.sh [days]
-
-set -e
-
-# Default to 30 days if not specified
-DAYS=${1:-30}
-
-echo "Running TurboQuant upstream watch for last $DAYS days..."
-
-# Check if GitHub token is set (env var or ~/.config/github/token file)
-if [ -z "$GITHUB_TOKEN" ] && [ -f "$HOME/.config/github/token" ]; then
-    export GITHUB_TOKEN=$(cat "$HOME/.config/github/token" | tr -d '[:space:]')
-    echo "Loaded GitHub token from ~/.config/github/token"
-fi
-
-if [ -z "$GITHUB_TOKEN" ]; then
-    echo "Warning: GITHUB_TOKEN not set. Using unauthenticated API (60 req/hour limit)."
-    echo "Set GITHUB_TOKEN or create ~/.config/github/token for higher rate limits."
-    echo ""
-fi
-
-# Run the monitor
-python3 scripts/upstream_watch.py --days "$DAYS" --format text --output upstream-report.md
-
-# Also generate JSON report
-python3 scripts/upstream_watch.py --days "$DAYS" --format json --output upstream-report.json
-
-echo ""
-echo "Reports generated:"
-echo "  - upstream-report.md (text format)"
-echo "  - upstream-report.json (JSON format)"
-echo ""
-
-# Check if there are findings
-FINDINGS=$(python3 -c "import json; data=json.load(open('upstream-report.json')); print(data['total_found'])")
-
-if [ "$FINDINGS" -gt 0 ]; then
-    echo "⚠️ Found $FINDINGS TurboQuant mentions in upstream repositories"
-    echo "Review upstream-report.md for details"
-else
-    echo "✅ No TurboQuant mentions found in upstream repositories"
-    echo "Recommendation: Continue using fork, re-check in $DAYS days"
-fi

scripts/test_upstream_watch.py

@@ -1,79 +0,0 @@
-#!/usr/bin/env python3
-"""
-Test script for upstream_watch.py - validates basic functionality without making API calls.
-"""
-
-import sys
-import os
-
-# Add the scripts directory to path
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from upstream_watch import UpstreamWatch
-
-def test_basic_functionality():
-    """Test basic functionality without making API calls."""
-    print("Testing basic functionality...")
-    
-    # Test initialization
-    monitor = UpstreamWatch()
-    print("✓ UpstreamWatch initialized")
-    
-    # Test keyword list
-    from upstream_watch import KEYWORDS
-    print(f"✓ Keywords configured: {len(KEYWORDS)} keywords")
-    
-    # Test report generation structure
-    print("\nTesting report generation structure...")
-    
-    # Create a mock report
-    mock_report = {
-        "scan_date": "2026-04-15T02:30:00Z",
-        "days_scanned": 7,
-        "llama_cpp_results": [],
-        "ollama_results": [],
-        "ggml_results": [],
-        "ollama_releases": [],
-        "fork_status": {
-            "fork_url": "https://github.com/TheTom/llama-cpp-turboquant",
-            "status": "active",
-            "last_updated": "2026-04-15T02:30:00Z",
-            "upstream_version": "unknown",
-            "fork_version": "unknown"
-        },
-        "total_found": 0
-    }
-    
-    print("✓ Report structure validated")
-    
-    # Test text report generation
-    print("\nSample text report:")
-    print("="*60)
-    print("TurboQuant Upstream Watch Report")
-    print("Generated: 2026-04-15T02:30:00Z")
-    print("Scanned: Last 7 days")
-    print("="*60)
-    print("\n## Summary")
-    print("- llama.cpp mentions: 0")
-    print("- Ollama mentions: 0")
-    print("- ggml mentions: 0")
-    print("- Ollama releases with keywords: 0")
-    print("- Total findings: 0")
-    print("\n## Fork Status")
-    print("- Fork URL: https://github.com/TheTom/llama-cpp-turboquant")
-    print("- Status: active")
-    print("- Last Updated: 2026-04-15T02:30:00Z")
-    print("\n## Conclusion")
-    print("No TurboQuant/PolarQuant/QJL mentions found in upstream repositories.")
-    print("Recommendation: Continue using fork, re-check in 7 days.")
-    
-    print("\n✓ All basic tests passed!")
-    return True
-
-if __name__ == "__main__":
-    try:
-        success = test_basic_functionality()
-        sys.exit(0 if success else 1)
-    except Exception as e:
-        print(f"Test failed: {e}")
-        sys.exit(1)

scripts/upstream_watch.py

@@ -1,251 +0,0 @@
-#!/usr/bin/env python3
-"""
-TurboQuant Upstream Watch Monitor
-Monitors llama.cpp and Ollama for TurboQuant/PolarQuant/QJL support.
-
-Issue #15: [P4] Upstream llama.cpp / Ollama TurboQuant watch
-"""
-
-import json
-import os
-import sys
-import urllib.request
-import subprocess
-from datetime import datetime, timedelta
-from typing import Dict, List, Any, Optional
-import argparse
-
-# Configuration
-GITHUB_API = "https://api.github.com"
-LLAMA_CPP_REPO = "ggerganov/llama.cpp"
-OLLAMA_REPO = "ollama/ollama"
-GGML_REPO = "ggml-org/ggml"
-
-# Keywords to search for
-KEYWORDS = [
-    "turborot", "turborotquant", "polarquant", "qjl",
-    "kv cache compression", "kv cache quantization",
-    "quantized kv", "kv quant", "cache compression"
-]
-
-class UpstreamWatch:
-    def __init__(self, github_token: Optional[str] = None):
-        self.github_token = github_token or os.environ.get("GITHUB_TOKEN")
-        # Fallback: read from ~/.config/github/token file
-        if not self.github_token:
-            token_path = os.path.expanduser("~/.config/github/token")
-            if os.path.isfile(token_path):
-                try:
-                    with open(token_path) as f:
-                        self.github_token = f.read().strip()
-                except Exception:
-                    pass
-        self.headers = {"Accept": "application/vnd.github.v3+json"}
-        if self.github_token:
-            self.headers["Authorization"] = f"token {self.github_token}"
-    
-    def _github_request(self, endpoint: str) -> Any:
-        """Make a GitHub API request."""
-        url = f"{GITHUB_API}{endpoint}"
-        req = urllib.request.Request(url, headers=self.headers)
-        
-        try:
-            with urllib.request.urlopen(req) as resp:
-                return json.loads(resp.read())
-        except urllib.error.HTTPError as e:
-            print(f"GitHub API error: {e.code} - {e.reason}")
-            return None
-    
-    def search_repo_issues_prs(self, repo: str, keywords: List[str], days: int = 30) -> List[Dict]:
-        """Search for issues and PRs in a repository."""
-        import urllib.parse
-        results = []
-        since = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ")
-        
-        for keyword in keywords:
-            # URL encode the keyword
-            encoded_keyword = urllib.parse.quote(keyword)
-            
-            # Search issues
-            endpoint = f"/repos/{repo}/issues?q={encoded_keyword}+created:>{since}&sort=updated&order=desc"
-            data = self._github_request(endpoint)
-            
-            if data and "items" in data:
-                for item in data["items"]:
-                    # Filter out PRs (they appear in issues endpoint too)
-                    if "pull_request" not in item:
-                        results.append({
-                            "type": "issue",
-                            "repo": repo,
-                            "number": item["number"],
-                            "title": item["title"],
-                            "url": item["html_url"],
-                            "created": item["created_at"],
-                            "updated": item["updated_at"],
-                            "keyword": keyword
-                        })
-            
-            # Search PRs
-            endpoint = f"/repos/{repo}/pulls?q={encoded_keyword}+created:>{since}&sort=updated&order=desc"
-            data = self._github_request(endpoint)
-            
-            if data and "items" in data:
-                for item in data["items"]:
-                    results.append({
-                        "type": "pr",
-                        "repo": repo,
-                        "number": item["number"],
-                        "title": item["title"],
-                        "url": item["html_url"],
-                        "created": item["created_at"],
-                        "updated": item["updated_at"],
-                        "keyword": keyword
-                    })
-        
-        return results
-    
-    def check_ollama_releases(self, days: int = 30) -> List[Dict]:
-        """Check Ollama releases for TurboQuant mentions."""
-        releases = []
-        endpoint = f"/repos/{OLLAMA_REPO}/releases"
-        data = self._github_request(endpoint)
-        
-        if data:
-            since = datetime.now() - timedelta(days=days)
-            for release in data:
-                published = datetime.strptime(release["published_at"], "%Y-%m-%dT%H:%M:%SZ")
-                if published > since:
-                    # Check release notes for keywords
-                    body = release.get("body", "").lower()
-                    found_keywords = [kw for kw in KEYWORDS if kw.lower() in body]
-                    
-                    if found_keywords:
-                        releases.append({
-                            "version": release["tag_name"],
-                            "name": release["name"],
-                            "url": release["html_url"],
-                            "published": release["published_at"],
-                            "keywords": found_keywords
-                        })
-        
-        return releases
-    
-    def get_fork_status(self) -> Dict[str, Any]:
-        """Get status of our TurboQuant fork."""
-        # This would typically check the local fork status
-        # For now, return placeholder data
-        return {
-            "fork_url": "https://github.com/TheTom/llama-cpp-turboquant",
-            "status": "active",
-            "last_updated": datetime.now().isoformat(),
-            "upstream_version": "unknown",
-            "fork_version": "unknown"
-        }
-    
-    def generate_report(self, days: int = 30, format: str = "text") -> str:
-        """Generate a monitoring report."""
-        print(f"Scanning upstream for TurboQuant mentions (last {days} days)...")
-        
-        # Search llama.cpp
-        llama_results = self.search_repo_issues_prs(LLAMA_CPP_REPO, KEYWORDS, days)
-        
-        # Search Ollama
-        ollama_results = self.search_repo_issues_prs(OLLAMA_REPO, KEYWORDS, days)
-        
-        # Search ggml
-        ggml_results = self.search_repo_issues_prs(GGML_REPO, KEYWORDS, days)
-        
-        # Check Ollama releases
-        ollama_releases = self.check_ollama_releases(days)
-        
-        # Get fork status
-        fork_status = self.get_fork_status()
-        
-        # Combine all results
-        all_results = llama_results + ollama_results + ggml_results
-        
-        if format == "json":
-            return json.dumps({
-                "scan_date": datetime.now().isoformat(),
-                "days_scanned": days,
-                "llama_cpp_results": llama_results,
-                "ollama_results": ollama_results,
-                "ggml_results": ggml_results,
-                "ollama_releases": ollama_releases,
-                "fork_status": fork_status,
-                "total_found": len(all_results)
-            }, indent=2)
-        else:
-            # Text format
-            report = f"TurboQuant Upstream Watch Report\n"
-            report += f"Generated: {datetime.now().isoformat()}\n"
-            report += f"Scanned: Last {days} days\n"
-            report += f"{'='*60}\n\n"
-            
-            report += f"## Summary\n"
-            report += f"- llama.cpp mentions: {len(llama_results)}\n"
-            report += f"- Ollama mentions: {len(ollama_results)}\n"
-            report += f"- ggml mentions: {len(ggml_results)}\n"
-            report += f"- Ollama releases with keywords: {len(ollama_releases)}\n"
-            report += f"- Total findings: {len(all_results)}\n\n"
-            
-            if all_results:
-                report += f"## Findings\n"
-                for result in all_results[:10]:  # Limit to first 10
-                    report += f"- [{result['type'].upper()}] {result['repo']}#{result['number']}: {result['title']}\n"
-                    report += f"  URL: {result['url']}\n"
-                    report += f"  Keyword: {result['keyword']}\n"
-                    report += f"  Updated: {result['updated']}\n\n"
-            
-            if ollama_releases:
-                report += f"## Ollama Releases with TurboQuant Mentions\n"
-                for release in ollama_releases:
-                    report += f"- {release['version']}: {release['name']}\n"
-                    report += f"  URL: {release['url']}\n"
-                    report += f"  Keywords: {', '.join(release['keywords'])}\n"
-                    report += f"  Published: {release['published']}\n\n"
-            
-            report += f"## Fork Status\n"
-            report += f"- Fork URL: {fork_status['fork_url']}\n"
-            report += f"- Status: {fork_status['status']}\n"
-            report += f"- Last Updated: {fork_status['last_updated']}\n\n"
-            
-            if not all_results and not ollama_releases:
-                report += f"## Conclusion\n"
-                report += f"No TurboQuant/PolarQuant/QJL mentions found in upstream repositories.\n"
-                report += f"Recommendation: Continue using fork, re-check in {days} days.\n"
-            else:
-                report += f"## Conclusion\n"
-                report += f"Found {len(all_results)} mentions in upstream repositories.\n"
-                report += f"Evaluate whether to migrate to upstream or continue using fork.\n"
-            
-            return report
-
-
-def main():
-    """Main entry point."""
-    parser = argparse.ArgumentParser(description="TurboQuant Upstream Watch Monitor")
-    parser.add_argument("--days", type=int, default=30, help="Number of days to scan (default: 30)")
-    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format")
-    parser.add_argument("--output", help="Output file (default: stdout)")
-    parser.add_argument("--github-token", help="GitHub API token (or set GITHUB_TOKEN env var)")
-    
-    args = parser.parse_args()
-    
-    # Initialize monitor
-    monitor = UpstreamWatch(args.github_token)
-    
-    # Generate report
-    report = monitor.generate_report(args.days, args.format)
-    
-    # Output report
-    if args.output:
-        with open(args.output, "w") as f:
-            f.write(report)
-        print(f"Report saved to {args.output}")
-    else:
-        print(report)
-
-
-if __name__ == "__main__":
-    main()

tests/conftest.py

@@ -0,0 +1,3 @@
+"""Pytest configuration for turboquant."""
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

tests/roundtrip_test.cpp

@@ -0,0 +1,104 @@
+#include "llama-turbo.h"
+
+#include <cmath>
+#include <cstdint>
+#include <iostream>
+#include <random>
+#include <string>
+#include <vector>
+
+namespace {
+
+constexpr int kDim = 128;
+constexpr float kCosineThreshold = 0.99f;
+constexpr float kZeroTolerance = 1.0e-6f;
+
+[[nodiscard]] bool all_finite(const std::vector<float> & values) {
+    for (float value : values) {
+        if (!std::isfinite(value)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+[[nodiscard]] float max_abs(const std::vector<float> & values) {
+    float best = 0.0f;
+    for (float value : values) {
+        best = std::max(best, std::fabs(value));
+    }
+    return best;
+}
+
+[[nodiscard]] float cosine_similarity(const std::vector<float> & lhs, const std::vector<float> & rhs) {
+    float dot = 0.0f;
+    float lhs_norm = 0.0f;
+    float rhs_norm = 0.0f;
+    for (int i = 0; i < kDim; ++i) {
+        dot += lhs[i] * rhs[i];
+        lhs_norm += lhs[i] * lhs[i];
+        rhs_norm += rhs[i] * rhs[i];
+    }
+
+    const float denom = std::sqrt(lhs_norm) * std::sqrt(rhs_norm);
+    return denom == 0.0f ? 1.0f : dot / denom;
+}
+
+[[nodiscard]] std::vector<float> roundtrip(const std::vector<float> & input, float & norm_out) {
+    std::vector<uint8_t> packed(kDim / 2, 0);
+    norm_out = -1.0f;
+    polar_quant_encode_turbo4(input.data(), packed.data(), &norm_out, kDim);
+
+    std::vector<float> decoded(kDim, 0.0f);
+    polar_quant_decode_turbo4(packed.data(), decoded.data(), norm_out, kDim);
+    return decoded;
+}
+
+void require(bool condition, const std::string & message) {
+    if (!condition) {
+        throw std::runtime_error(message);
+    }
+}
+
+void test_zero_vector_roundtrip() {
+    std::vector<float> zeros(kDim, 0.0f);
+    float norm = -1.0f;
+    const auto decoded = roundtrip(zeros, norm);
+
+    require(norm == 0.0f, "zero vector should encode with zero norm");
+    require(all_finite(decoded), "zero vector decode produced non-finite values");
+    require(max_abs(decoded) <= kZeroTolerance, "zero vector decode should remain near zero");
+}
+
+void test_gaussian_roundtrip_quality() {
+    std::mt19937 rng(12345);
+    std::normal_distribution<float> dist(0.0f, 1.0f);
+
+    std::vector<float> input(kDim, 0.0f);
+    for (float & value : input) {
+        value = dist(rng);
+    }
+
+    float norm = -1.0f;
+    const auto decoded = roundtrip(input, norm);
+
+    require(norm > 0.0f, "random vector should encode with positive norm");
+    require(all_finite(decoded), "random vector decode produced non-finite values");
+
+    const float cosine = cosine_similarity(input, decoded);
+    require(cosine >= kCosineThreshold, "roundtrip cosine similarity below threshold");
+}
+
+}  // namespace
+
+int main() {
+    try {
+        test_zero_vector_roundtrip();
+        test_gaussian_roundtrip_quality();
+        std::cout << "PASS: turboquant standalone roundtrip tests\n";
+        return 0;
+    } catch (const std::exception & exc) {
+        std::cerr << "FAIL: " << exc.what() << '\n';
+        return 1;
+    }
+}

tests/test_hardware_optimizer.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Tests for hardware_optimizer compatibility shim."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+from evolution import hardware_optimizer, quant_selector
+
+
+def test_hardware_optimizer_reexports_quant_selector_api():
+    assert hardware_optimizer.select_quant_level is quant_selector.select_quant_level
+    assert hardware_optimizer.detect_hardware is quant_selector.detect_hardware
+    assert hardware_optimizer.HardwareInfo is quant_selector.HardwareInfo
+    assert hardware_optimizer.QuantSelection is quant_selector.QuantSelection
+
+
+def test_hardware_optimizer_exports_quant_level_definitions():
+    assert hardware_optimizer.QUANT_LEVELS is quant_selector.QUANT_LEVELS
+    assert hardware_optimizer.QuantLevel is quant_selector.QuantLevel

tests/test_markdown_link_check.py

@@ -0,0 +1,74 @@
+import textwrap
+from pathlib import Path
+
+from check_markdown_links import find_broken_links
+
+
+def write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(textwrap.dedent(content).lstrip(), encoding="utf-8")
+
+
+def test_reports_missing_local_markdown_target_with_line_number(tmp_path: Path):
+    write(
+        tmp_path / "README.md",
+        """
+        # Repo
+
+        See [status](docs/status.md).
+        """,
+    )
+
+    broken = find_broken_links(tmp_path)
+
+    assert len(broken) == 1
+    assert broken[0]["source"].endswith("README.md")
+    assert broken[0]["line"] == 3
+    assert broken[0]["target"] == "docs/status.md"
+
+
+def test_allows_existing_relative_targets(tmp_path: Path):
+    write(tmp_path / "docs" / "status.md", "# Status\n")
+    write(
+        tmp_path / "README.md",
+        """
+        # Repo
+
+        See [status](docs/status.md).
+        """,
+    )
+
+    assert find_broken_links(tmp_path) == []
+
+
+def test_ignores_external_anchor_mailto_and_tel_links(tmp_path: Path):
+    write(
+        tmp_path / "README.md",
+        """
+        [external](https://example.com)
+        [anchor](#section)
+        [mail](mailto:test@example.com)
+        [call](tel:988)
+        """,
+    )
+
+    assert find_broken_links(tmp_path) == []
+
+
+def test_ignores_links_inside_fenced_code_blocks(tmp_path: Path):
+    write(
+        tmp_path / "README.md",
+        """
+        ```md
+        [broken](docs/missing.md)
+        ```
+        """,
+    )
+
+    assert find_broken_links(tmp_path) == []
+
+
+def test_skips_build_directories(tmp_path: Path):
+    write(tmp_path / "build" / "README.md", "[broken](missing.md)\n")
+
+    assert find_broken_links(tmp_path) == []

tests/test_quant_selector.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Tests for quant_selector.py"""
+
+import sys
+import os
+import pytest
+from unittest.mock import patch, MagicMock
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+from evolution.quant_selector import (
+    QuantLevel,
+    HardwareInfo,
+    QUANT_LEVELS,
+    detect_hardware,
+    estimate_kv_cache_gb,
+    estimate_model_memory_gb,
+    select_quant_level,
+)
+
+
+class TestQuantLevels:
+    def test_levels_ordered_by_quality(self):
+        """TurboQuant levels should be ordered from best quality to most aggressive.
+
+        The quality ordering invariant for TurboQuant levels is monotonically
+        increasing compression_ratio (more aggressive = more compression).
+        Non-TurboQuant fallbacks (e.g. q4_0) are placed after all TurboQuant
+        levels and may have any compression ratio — they exist as safe defaults,
+        not as part of the quality progression.
+        """
+        turbo_quant_names = {"turbo4", "turbo3", "turbo2"}
+        turbo_levels = [l for l in QUANT_LEVELS if l.name in turbo_quant_names]
+        for i in range(len(turbo_levels) - 1):
+            assert turbo_levels[i].compression_ratio <= turbo_levels[i + 1].compression_ratio, (
+                f"TurboQuant {turbo_levels[i].name} (compression={turbo_levels[i].compression_ratio}x) "
+                f"should have <= compression than {turbo_levels[i+1].name} "
+                f"(compression={turbo_levels[i+1].compression_ratio}x)"
+            )
+
+    def test_fallback_quant_is_last(self):
+        """Non-TurboQuant fallbacks (e.g. q4_0) should be at the end of the list."""
+        turbo_quant_names = {"turbo4", "turbo3", "turbo2"}
+        found_fallback = False
+        for level in QUANT_LEVELS:
+            if level.name not in turbo_quant_names:
+                found_fallback = True
+            elif found_fallback:
+                pytest.fail(
+                    f"TurboQuant level '{level.name}' appears after a fallback level. "
+                    f"All TurboQuant levels must precede fallbacks."
+                )
+
+    def test_all_levels_have_required_fields(self):
+        for level in QUANT_LEVELS:
+            assert level.name
+            assert level.bits_per_channel > 0
+            assert level.compression_ratio > 1
+            assert level.quality_label
+            assert level.layer_adaptive >= 0
+            assert level.kv_type
+
+
+class TestKVEstimate:
+    def test_basic_estimate(self):
+        # 48 layers, 8 heads, 128 dim, 32K context, 3.5 bits
+        kv_gb = estimate_kv_cache_gb(32768, 48, 8, 128, 3.5)
+        assert kv_gb > 0
+        assert kv_gb < 10  # Should be reasonable
+
+    def test_longer_context_larger(self):
+        kv_32k = estimate_kv_cache_gb(32768, 48, 8, 128, 3.5)
+        kv_128k = estimate_kv_cache_gb(131072, 48, 8, 128, 3.5)
+        assert kv_128k > kv_32k
+
+    def test_higher_bits_larger(self):
+        kv_4b = estimate_kv_cache_gb(32768, 48, 8, 128, 4.0)
+        kv_2b = estimate_kv_cache_gb(32768, 48, 8, 128, 2.0)
+        assert kv_4b > kv_2b
+
+
+class TestHardwareDetection:
+    def test_detect_returns_info(self):
+        hw = detect_hardware()
+        assert hw.total_memory_gb > 0
+        assert hw.available_memory_gb > 0
+        assert hw.detection_method
+
+    @patch("evolution.quant_selector.platform.system", return_value="Linux")
+    @patch("builtins.open", create=True)
+    def test_linux_detection(self, mock_open, mock_system):
+        mock_open.return_value.__enter__().read.return_value = (
+            "MemTotal:       32000000 kB\n"
+            "MemAvailable:   24000000 kB\n"
+        )
+        hw = _detect_linux_fallback()
+        assert hw.total_memory_gb > 20
+
+
+def _detect_linux_fallback():
+    """Helper to test Linux detection with mocked /proc/meminfo."""
+    from evolution.quant_selector import _detect_linux
+    return _detect_linux()
+
+
+class TestSelection:
+    def test_selects_turbo4_for_large_memory(self):
+        """With plenty of memory, should pick turbo4 (best quality)."""
+        with patch("evolution.quant_selector.detect_hardware") as mock_hw:
+            mock_hw.return_value = HardwareInfo(
+                total_memory_gb=64,
+                available_memory_gb=48,
+                gpu_memory_gb=64,
+                gpu_name="Test GPU",
+                cpu_cores=16,
+                detection_method="mock",
+            )
+            sel = select_quant_level(model_size_gb=14.0, context_length=32768)
+            assert sel.level.name == "turbo4"
+            assert sel.headroom_gb > 0
+
+    def test_selects_smaller_for_tight_memory(self):
+        """With tight memory, should pick a smaller quant."""
+        with patch("evolution.quant_selector.detect_hardware") as mock_hw:
+            mock_hw.return_value = HardwareInfo(
+                total_memory_gb=16,
+                available_memory_gb=12,
+                gpu_memory_gb=16,
+                gpu_name="Test GPU",
+                cpu_cores=8,
+                detection_method="mock",
+            )
+            sel = select_quant_level(model_size_gb=14.0, context_length=131072)
+            # Should pick a smaller quant for 128K context on 16GB
+            assert sel.level.bits_per_channel <= 4.0
+
+    def test_preferred_level(self):
+        """User can force a specific level."""
+        with patch("evolution.quant_selector.detect_hardware") as mock_hw:
+            mock_hw.return_value = HardwareInfo(
+                total_memory_gb=64,
+                available_memory_gb=48,
+                cpu_cores=16,
+                detection_method="mock",
+            )
+            sel = select_quant_level(
+                model_size_gb=14.0, context_length=32768,
+                preferred_level="turbo2"
+            )
+            assert sel.level.name == "turbo2"
+
+    def test_env_vars_populated(self):
+        with patch("evolution.quant_selector.detect_hardware") as mock_hw:
+            mock_hw.return_value = HardwareInfo(
+                total_memory_gb=64,
+                available_memory_gb=48,
+                cpu_cores=16,
+                detection_method="mock",
+            )
+            sel = select_quant_level(model_size_gb=14.0, context_length=32768)
+            assert "TURBO_LAYER_ADAPTIVE" in sel.env_vars
+            assert "-ctk" in sel.server_flags
+            assert "-ctv" in sel.server_flags
+
+    def test_warnings_on_low_headroom(self):
+        with patch("evolution.quant_selector.detect_hardware") as mock_hw:
+            mock_hw.return_value = HardwareInfo(
+                total_memory_gb=18,
+                available_memory_gb=14,
+                gpu_memory_gb=18,
+                gpu_name="Test GPU",
+                cpu_cores=8,
+                detection_method="mock",
+            )
+            sel = select_quant_level(model_size_gb=16.0, context_length=65536)
+            assert len(sel.warnings) > 0
+
+    def test_reasoning_contains_key_info(self):
+        with patch("evolution.quant_selector.detect_hardware") as mock_hw:
+            mock_hw.return_value = HardwareInfo(
+                total_memory_gb=32,
+                available_memory_gb=24,
+                is_apple_silicon=True,
+                chip_name="M4 Max",
+                cpu_cores=16,
+                detection_method="mock",
+            )
+            sel = select_quant_level(model_size_gb=14.0, context_length=32768)
+            assert "turbo4" in sel.reasoning
+            assert "M4 Max" in sel.reasoning or "32GB" in sel.reasoning

tests/test_smoke_workflow.py

@@ -0,0 +1,83 @@
+"""Tests for smoke workflow CI configuration.
+
+Validates that the GitHub Actions / Gitea Actions smoke workflow
+actually runs the standalone CMake build and test suite, not just
+parse checks.
+"""
+
+from pathlib import Path
+
+import yaml
+
+import pytest
+
+
+WORKFLOW_PATH = Path(".gitea/workflows/smoke.yml")
+
+
+@pytest.fixture
+def workflow():
+    """Load and parse the smoke workflow YAML."""
+    content = WORKFLOW_PATH.read_text(encoding="utf-8")
+    return yaml.safe_load(content)
+
+
+def test_smoke_workflow_exists():
+    """Smoke workflow file must exist."""
+    assert WORKFLOW_PATH.exists(), f"Missing {WORKFLOW_PATH}"
+
+
+def test_smoke_has_cmake_configure_step(workflow):
+    """Smoke workflow must configure the CMake project with tests enabled."""
+    steps = workflow["jobs"]["smoke"]["steps"]
+    cmake_found = False
+    for step in steps:
+        run = step.get("run", "")
+        if "cmake -S . -B build" in run and "TURBOQUANT_BUILD_TESTS=ON" in run:
+            cmake_found = True
+            break
+    assert cmake_found, (
+        "Smoke workflow missing cmake configure step with TURBOQUANT_BUILD_TESTS=ON"
+    )
+
+
+def test_smoke_has_cmake_build_step(workflow):
+    """Smoke workflow must build the CMake project."""
+    steps = workflow["jobs"]["smoke"]["steps"]
+    build_found = False
+    for step in steps:
+        run = step.get("run", "")
+        if "cmake --build build" in run:
+            build_found = True
+            break
+    assert build_found, "Smoke workflow missing cmake --build step"
+
+
+def test_smoke_has_ctest_step(workflow):
+    """Smoke workflow must run ctest."""
+    steps = workflow["jobs"]["smoke"]["steps"]
+    ctest_found = False
+    for step in steps:
+        run = step.get("run", "")
+        if "ctest" in run and "output-on-failure" in run:
+            ctest_found = True
+            break
+    assert ctest_found, "Smoke workflow missing ctest --output-on-failure step"
+
+
+def test_smoke_build_before_secret_scan(workflow):
+    """Build and test steps must run before secret scan (fail fast on build errors)."""
+    steps = workflow["jobs"]["smoke"]["steps"]
+    names = [s.get("name", "") for s in steps]
+    build_idx = None
+    scan_idx = None
+    for i, name in enumerate(names):
+        if "cmake" in name.lower() or "build" in name.lower():
+            if build_idx is None:
+                build_idx = i
+        if "secret" in name.lower():
+            scan_idx = i
+    if build_idx is not None and scan_idx is not None:
+        assert build_idx < scan_idx, (
+            "Build step should run before secret scan to fail fast on broken code"
+        )

tests/test_tool_call_integration.py

@@ -0,0 +1,338 @@
+"""
+Integration test: turboquant compressed model passes hermes tool calls (issue #82).
+
+Validates that a TurboQuant-compressed model can:
+1. Parse hermes tool schemas correctly
+2. Format tool calls in OpenAI-compatible format
+3. Pass through the hermes agent conversation loop
+
+Tests are structured as contract tests -- they validate the schema/format
+compatibility without requiring a running model server. The live inference
+test is skipped by default (requires llama-server with TurboQuant model).
+
+Usage:
+    pytest tests/test_tool_call_integration.py -v
+    pytest tests/test_tool_call_integration.py -v -k live  # run live test if server available
+"""
+import json
+import os
+import pathlib
+import re
+import unittest
+
+import pytest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+PROFILE_PATH = ROOT / "profiles" / "hermes-profile-gemma4-turboquant.yaml"
+BENCHMARKS_DIR = ROOT / "benchmarks"
+
+
+class TestHermesProfileSchema(unittest.TestCase):
+    """Validate the hermes profile YAML has required fields for tool calling."""
+
+    @classmethod
+    def setUpClass(cls):
+        import yaml
+        cls.profile = yaml.safe_load(PROFILE_PATH.read_text())
+
+    def test_profile_has_providers(self):
+        assert "providers" in self.profile, "Profile must define providers"
+        assert "primary" in self.profile["providers"], "Must have primary provider"
+
+    def test_primary_provider_has_endpoint(self):
+        primary = self.profile["providers"]["primary"]
+        assert "endpoint" in primary, "Primary provider must have endpoint"
+        assert primary["endpoint"].startswith("http"), "Endpoint must be HTTP(S) URL"
+
+    def test_primary_provider_has_api_path(self):
+        primary = self.profile["providers"]["primary"]
+        assert "api_path" in primary, "Primary provider must have api_path"
+        assert "/chat/completions" in primary["api_path"], (
+            "api_path should be OpenAI-compatible /chat/completions"
+        )
+
+    def test_turboquant_settings_present(self):
+        primary = self.profile["providers"]["primary"]
+        assert "turboquant" in primary, "Must have turboquant config section"
+        tq = primary["turboquant"]
+        assert tq.get("enabled") is True, "TurboQuant must be enabled"
+        assert tq.get("kv_type") in ("turbo2", "turbo3", "turbo4"), (
+            "kv_type must be turbo2, turbo3, or turbo4"
+        )
+
+    def test_context_window_configured(self):
+        primary = self.profile["providers"]["primary"]
+        assert "context" in primary, "Must have context config"
+        ctx = primary["context"]
+        assert ctx.get("max_tokens", 0) >= 8192, (
+            "max_tokens should be >= 8192 for TurboQuant value proposition"
+        )
+
+
+class TestToolSchemaCompatibility(unittest.TestCase):
+    """Verify hermes tool schemas serialize to valid JSON for OpenAI tool_calls."""
+
+    SAMPLE_TOOL_SCHEMAS = [
+        {
+            "type": "function",
+            "function": {
+                "name": "read_file",
+                "description": "Read a text file with line numbers.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "description": "File path"},
+                        "offset": {"type": "integer", "default": 1},
+                        "limit": {"type": "integer", "default": 500},
+                    },
+                    "required": ["path"],
+                },
+            },
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "execute_code",
+                "description": "Run a Python script.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "code": {"type": "string", "description": "Python code"},
+                    },
+                    "required": ["code"],
+                },
+            },
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "web_search",
+                "description": "Search the web.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string"},
+                        "max_results": {"type": "integer", "default": 5},
+                    },
+                    "required": ["query"],
+                },
+            },
+        },
+    ]
+
+    def test_tool_schemas_serialize_to_json(self):
+        """Tool schemas must serialize without errors."""
+        serialized = json.dumps(self.SAMPLE_TOOL_SCHEMAS)
+        assert len(serialized) > 0
+        parsed = json.loads(serialized)
+        assert len(parsed) == len(self.SAMPLE_TOOL_SCHEMAS)
+
+    def test_tool_schemas_have_required_openai_fields(self):
+        """Each tool schema must have the fields OpenAI expects."""
+        for tool in self.SAMPLE_TOOL_SCHEMAS:
+            assert tool["type"] == "function", "Tool type must be 'function'"
+            fn = tool["function"]
+            assert "name" in fn, "Function must have name"
+            assert "description" in fn, "Function must have description"
+            assert "parameters" in fn, "Function must have parameters"
+            params = fn["parameters"]
+            assert params["type"] == "object", "Parameters type must be 'object'"
+            assert "properties" in params, "Parameters must have properties"
+
+    def test_tool_call_response_format(self):
+        """Verify tool_call response matches OpenAI format."""
+        tool_call = {
+            "id": "call_abc123",
+            "type": "function",
+            "function": {
+                "name": "read_file",
+                "arguments": json.dumps({"path": "/tmp/test.txt"}),
+            },
+        }
+        args = json.loads(tool_call["function"]["arguments"])
+        assert args["path"] == "/tmp/test.txt"
+        assert tool_call["function"]["name"] in [
+            t["function"]["name"] for t in self.SAMPLE_TOOL_SCHEMAS
+        ]
+
+    def test_tool_names_are_valid_identifiers(self):
+        """Tool names must be valid Python identifiers for hermes dispatch."""
+        for tool in self.SAMPLE_TOOL_SCHEMAS:
+            name = tool["function"]["name"]
+            assert re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name), (
+                f"Tool name \'{name}\' is not a valid identifier"
+            )
+
+
+class TestTurboquantServerConfig(unittest.TestCase):
+    """Validate server startup configuration matches hermes profile."""
+
+    def test_server_command_has_turboquant_flags(self):
+        """The server command in the profile must include -ctk/-ctv flags."""
+        profile_text = PROFILE_PATH.read_text()
+        assert "-ctk" in profile_text, "Profile server command must include -ctk flag"
+        assert "-ctv" in profile_text, "Profile server command must include -ctv flag"
+
+    def test_server_command_has_context_flag(self):
+        """Server command must set context size."""
+        profile_text = PROFILE_PATH.read_text()
+        assert re.search(r"-c\s+\d+", profile_text), (
+            "Server command must include -c <context_size> flag"
+        )
+
+    def test_layer_adaptive_env_var(self):
+        """Profile must set TURBO_LAYER_ADAPTIVE env var."""
+        profile_text = PROFILE_PATH.read_text()
+        assert "TURBO_LAYER_ADAPTIVE" in profile_text, (
+            "Profile must configure TURBO_LAYER_ADAPTIVE"
+        )
+
+
+class TestBenchmarkData(unittest.TestCase):
+    """Validate benchmark test prompts include tool-call test cases."""
+
+    @classmethod
+    def setUpClass(cls):
+        prompts_path = BENCHMARKS_DIR / "test_prompts.json"
+        cls.prompts = json.loads(prompts_path.read_text())
+
+    def test_has_tool_call_test_prompt(self):
+        """Benchmark prompts must include a tool-call format test."""
+        categories = [p.get("category") for p in self.prompts]
+        assert "tool_call_format" in categories, (
+            "Benchmark must include a tool_call_format test case"
+        )
+
+    def test_tool_call_prompt_expects_json(self):
+        """Tool call test prompt must expect JSON in the response."""
+        tool_prompt = next(
+            p for p in self.prompts if p.get("category") == "tool_call_format"
+        )
+        pattern = tool_prompt.get("expected_pattern", "")
+        assert "json" in pattern.lower() or "\\{" in pattern, (
+            "Tool call prompt must expect JSON-formatted response"
+        )
+
+
+@pytest.mark.skipif(
+    not os.environ.get("TURBOQUANT_SERVER_URL"),
+    reason="No TurboQuant server available (set TURBOQUANT_SERVER_URL to run)",
+)
+class TestLiveToolCallIntegration:
+    """Live integration test -- requires running llama-server with TurboQuant."""
+
+    def test_server_health(self):
+        """Server must respond to /v1/models endpoint."""
+        import requests
+        url = os.environ["TURBOQUANT_SERVER_URL"]
+        resp = requests.get(f"{url}/v1/models", timeout=10)
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "data" in data
+        assert len(data["data"]) > 0
+
+    def test_tool_call_completion(self):
+        """Model must return a valid tool_call for a read_file prompt."""
+        import requests
+        url = os.environ["TURBOQUANT_SERVER_URL"]
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "read_file",
+                    "description": "Read a file",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"path": {"type": "string"}},
+                        "required": ["path"],
+                    },
+                },
+            }
+        ]
+        resp = requests.post(
+            f"{url}/v1/chat/completions",
+            json={
+                "model": "gemma-4",
+                "messages": [
+                    {"role": "user", "content": "Read the file at /tmp/test.txt"}
+                ],
+                "tools": tools,
+                "tool_choice": "auto",
+            },
+            timeout=120,
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        choice = data["choices"][0]
+        msg = choice["message"]
+        if "tool_calls" in msg and msg["tool_calls"]:
+            tc = msg["tool_calls"][0]
+            assert tc["type"] == "function"
+            assert tc["function"]["name"] == "read_file"
+            args = json.loads(tc["function"]["arguments"])
+            assert "path" in args
+        else:
+            assert len(msg.get("content", "")) > 0
+
+    def test_tool_call_with_multiple_tools(self):
+        """Model must handle multiple available tools."""
+        import requests
+        url = os.environ["TURBOQUANT_SERVER_URL"]
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": "read_file",
+                    "description": "Read a file",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"path": {"type": "string"}},
+                        "required": ["path"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "web_search",
+                    "description": "Search the web",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"query": {"type": "string"}},
+                        "required": ["query"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "execute_code",
+                    "description": "Run Python code",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {"code": {"type": "string"}},
+                        "required": ["code"],
+                    },
+                },
+            },
+        ]
+        resp = requests.post(
+            f"{url}/v1/chat/completions",
+            json={
+                "model": "gemma-4",
+                "messages": [
+                    {"role": "user", "content": "Search the web for 'bitcoin price'"}
+                ],
+                "tools": tools,
+                "tool_choice": "auto",
+            },
+            timeout=120,
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "choices" in data
+        assert len(data["choices"]) > 0
+
+
+if __name__ == "__main__":
+    unittest.main()