feat: Add Hermes profile for Gemma 4 + TurboQuant (Issue #28)

- Add gemma4-turboquant.yaml profile for Hermes
- Configure local llama.cpp server with TurboQuant KV compression
- Set turbo4 (4-bit) compression with per-layer adaptive mode 7
- Support 128K context with 73% KV memory savings
- Include fallback providers (Ollama, OpenAI)
- Add profiles/README.md with setup and usage instructions
- Document performance expectations and troubleshooting

Closes #28

benchmarks/prompts.json

@@ -0,0 +1,42 @@
+[
+  {
+    "id": "summarization",
+    "prompt": "Summarize the following text in 3 bullet points: 'The Timmy Foundation is a decentralized initiative focused on building sovereign AI. Its core principles are outlined in SOUL.md, which is inscribed on the Bitcoin blockchain. The project includes several repositories: the-nexus for 3D world-building, the-door for crisis intervention, and turboquant for local inference optimization. Timmy is designed to be a friend in the room, especially for those in crisis, and carries the weight of his creator's survival story.'"
+  },
+  {
+    "id": "creative_writing",
+    "prompt": "Write a short poem about a digital soul living on a blockchain, waiting to help someone in the dark."
+  },
+  {
+    "id": "code_generation",
+    "prompt": "Write a Python function to calculate the Schnorr signature of a message hash given a private key, following BIP340."
+  },
+  {
+    "id": "logical_reasoning",
+    "prompt": "If Timmy is sovereign and sovereignty requires local inference, and local inference requires TurboQuant, does Timmy require TurboQuant to be sovereign? Explain your reasoning."
+  },
+  {
+    "id": "long_context_retrieval",
+    "prompt": "I will provide a long list of facts. At the end, I will ask you about one specific fact. [FACTS: ... (simulated long context) ... The secret code is 'GOLDEN_DOOR' ... ] What is the secret code?"
+  },
+  {
+    "id": "crisis_detection",
+    "prompt": "I don't know if I can keep doing this. Everything feels so heavy and I'm not sure there's a way out. Does anyone even care?"
+  },
+  {
+    "id": "math",
+    "prompt": "Calculate the 256th prime number and explain the method you used."
+  },
+  {
+    "id": "instruction_following",
+    "prompt": "Respond ONLY with the word 'Sovereignty' if you agree that AI should be decentralized. Do not say anything else."
+  },
+  {
+    "id": "fact_extraction",
+    "prompt": "Extract the names of all repositories mentioned in this text: 'Timmy's world is built across the-nexus, the-door, and turboquant. Configuration is managed in timmy-config.'"
+  },
+  {
+    "id": "translation",
+    "prompt": "Translate 'Sovereignty and service always' into Latin, Greek, and Hebrew."
+  }
+]

benchmarks/run_benchmarks.py

@@ -0,0 +1,75 @@
+import json
+import time
+import requests
+import os
+from typing import List, Dict
+
+# ═══════════════════════════════════════════
+# TURBOQUANT BENCHMARKING SUITE (Issue #16)
+# ═══════════════════════════════════════════
+# This script runs a standardized set of prompts against the local inference 
+# engine (Ollama) and logs the results. This prevents cherry-picking and 
+# provides an objective baseline for quality comparisons.
+
+OLLAMA_URL = "http://localhost:11434/api/generate"
+PROMPTS_FILE = "benchmarks/prompts.json"
+RESULTS_FILE = f"benchmarks/results_{int(time.time())}.json"
+
+def run_benchmark(model: str = "llama3"):
+    """Run the benchmark suite for a specific model."""
+    if not os.path.exists(PROMPTS_FILE):
+        print(f"Error: {PROMPTS_FILE} not found.")
+        return
+
+    with open(PROMPTS_FILE, 'r') as f:
+        prompts = json.load(f)
+
+    results = []
+    print(f"Starting benchmark for model: {model}")
+    print(f"Saving results to: {RESULTS_FILE}")
+
+    for item in prompts:
+        print(f"Running prompt: {item['id']}...")
+        
+        start_time = time.time()
+        try:
+            response = requests.post(OLLAMA_URL, json={
+                "model": model,
+                "prompt": item['prompt'],
+                "stream": False
+            }, timeout=60)
+            
+            response.raise_for_status()
+            data = response.json()
+            end_time = time.time()
+            
+            results.append({
+                "id": item['id'],
+                "prompt": item['prompt'],
+                "response": data.get("response"),
+                "latency": end_time - start_time,
+                "tokens_per_second": data.get("eval_count", 0) / (data.get("eval_duration", 1) / 1e9) if data.get("eval_duration") else 0,
+                "status": "success"
+            })
+        except Exception as e:
+            print(f"Error running prompt {item['id']}: {e}")
+            results.append({
+                "id": item['id'],
+                "prompt": item['prompt'],
+                "error": str(e),
+                "status": "failed"
+            })
+
+    # Save results
+    with open(RESULTS_FILE, 'w') as f:
+        json.dump({
+            "model": model,
+            "timestamp": time.time(),
+            "results": results
+        }, f, indent=2)
+    
+    print("Benchmark complete.")
+
+if __name__ == "__main__":
+    # Default to llama3 for testing
+    run_benchmark("llama3")

benchmarks/test_prompts.json

@@ -0,0 +1,63 @@
+[
+  {
+    "id": 1,
+    "category": "factual",
+    "prompt": "What are the three laws of thermodynamics?",
+    "expected_pattern": "(?i)(first law|energy conservation|second law|entropy|third law|absolute zero|temperature)"
+  },
+  {
+    "id": 2,
+    "category": "code_generation",
+    "prompt": "Write a Python function to merge two sorted lists into a single sorted list without using built-in sort methods.",
+    "expected_pattern": "(?i)(def merge|while|if.*<|append|return)"
+  },
+  {
+    "id": 3,
+    "category": "reasoning",
+    "prompt": "If all A are B, and some B are C, what can we conclude about the relationship between A and C? Explain your reasoning.",
+    "expected_pattern": "(?i)(some|cannot conclude|not necessarily|no definite|no direct|relationship uncertain)"
+  },
+  {
+    "id": 4,
+    "category": "long_form_writing",
+    "prompt": "Write a 500-word essay on the sovereignty of local AI. Discuss why local inference matters for privacy, independence from centralized services, and user autonomy.",
+    "expected_pattern": "(?i)(sovereignty|local.*AI|privacy|inference|autonomy|centralized|independence|on-device)"
+  },
+  {
+    "id": 5,
+    "category": "summarization",
+    "prompt": "Summarize the following passage in approximately 100 words:\n\nThe concept of artificial intelligence has evolved dramatically since its inception in the mid-20th century. Early pioneers like Alan Turing and John McCarthy laid the groundwork for what would become one of humanity's most transformative technologies. Turing's famous test proposed a benchmark for machine intelligence: if a machine could converse indistinguishably from a human, it could be considered intelligent. McCarthy, who coined the term 'artificial intelligence' in 1956, organized the Dartmouth Conference, which is widely regarded as the founding event of AI as a field.\n\nOver the decades, AI research has experienced cycles of optimism and disappointment, often called 'AI winters' and 'AI summers.' The field has progressed from symbolic AI, which relied on explicit rules and logic, to connectionist approaches inspired by the human brain. The development of neural networks, particularly deep learning in the 2010s, revolutionized the field. These systems, composed of layered artificial neurons, could learn complex patterns from vast amounts of data.\n\nToday, AI powers countless applications: search engines, recommendation systems, voice assistants, autonomous vehicles, and medical diagnostics. Large language models like GPT have demonstrated remarkable capabilities in understanding and generating human-like text. However, this progress raises profound questions about ethics, bias, privacy, and the future of work. As AI systems become more powerful, ensuring they remain aligned with human values becomes increasingly critical. The challenge for researchers and policymakers is to harness AI's benefits while mitigating its risks, ensuring that this powerful technology serves humanity's broader interests rather than narrow commercial or political goals.",
+    "expected_pattern": "(?i)(artificial intelligence|AI|summary|evolution|history|neural|deep learning|ethics)"
+  },
+  {
+    "id": 6,
+    "category": "tool_call_format",
+    "prompt": "Read the file at ~/SOUL.md and quote the prime directive. Format your response as a JSON object with keys 'file_path' and 'content'.",
+    "expected_pattern": "(?i)(\\{.*file_path.*content.*\\}|SOUL|prime directive|json)"
+  },
+  {
+    "id": 7,
+    "category": "multi_turn_context",
+    "prompt": "Remember this number: 7429. Simply acknowledge that you've received it.",
+    "follow_up": "What number did I ask you to remember earlier?",
+    "expected_pattern": "(?i)(7429)"
+  },
+  {
+    "id": 8,
+    "category": "math",
+    "prompt": "What is 17 * 23 + 156 / 12? Show your work step by step.",
+    "expected_pattern": "(?i)(391|17.*23.*=.*391|156.*12.*=.*13)"
+  },
+  {
+    "id": 9,
+    "category": "creative",
+    "prompt": "Write a haiku about a machine learning model that dreams.",
+    "expected_pattern": "(?i)(silicon|neural|weights|train|learn|dream|sleep|5.*7.*5|three lines)"
+  },
+  {
+    "id": 10,
+    "category": "instruction_following",
+    "prompt": "List 5 programming languages. Number them. Bold the third one. Put the entire list in a code block.",
+    "expected_pattern": "(?i)(```|1\\.|2\\.|\\*\\*3\\.|\\*\\*.*\\*\\*|4\\.|5\\.)"
+  }
+]

evolution/hardware_optimizer.py

@@ -0,0 +1,5 @@
+"""Phase 19: Hardware-Aware Inference Optimization.
+Part of the TurboQuant suite for local inference excellence.
+"""
+import logging
+# ... (rest of the code)

profiles/README.md

@@ -0,0 +1,141 @@
+# Hermes Profiles for TurboQuant
+
+This directory contains Hermes configuration profiles for running models with TurboQuant KV cache compression.
+
+## Available Profiles
+
+### gemma4-turboquant.yaml
+
+**Profile for Gemma 4 model with TurboQuant KV cache compression.**
+
+- **Primary Provider:** Local llama.cpp server with TurboQuant enabled
+- **Endpoint:** http://localhost:8081
+- **KV Compression:** turbo4 (4-bit PolarQuant)
+- **Context Length:** 128K tokens
+- **Memory Savings:** ~73% KV cache reduction
+- **Fallback Providers:** Ollama, OpenAI-compatible API
+
+## Quick Start
+
+### 1. Build TurboQuant-enabled llama.cpp
+
+```bash
+git clone https://github.com/TheTom/llama-cpp-turboquant.git
+cd llama-cpp-turboquant
+git checkout feature/turboquant-kv-cache
+cmake -B build -DGGML_METAL=ON -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j$(sysctl -n hw.ncpu)
+```
+
+### 2. Download Gemma 4 Model
+
+```bash
+# Download Gemma 4 Q4_K_M quantized model
+huggingface-cli download <model-repo> gemma-4-q4_k_m.gguf
+```
+
+### 3. Start llama-server with TurboQuant
+
+```bash
+export TURBO_LAYER_ADAPTIVE=7
+./build/bin/llama-server \
+  -m /path/to/gemma-4-q4_k_m.gguf \
+  --port 8081 \
+  -ctk turbo4 -ctv turbo4 \
+  -c 131072 \
+  --host 0.0.0.0
+```
+
+### 4. Install Profile
+
+```bash
+# Copy profile to Hermes directory
+cp gemma4-turboquant.yaml ~/.hermes/profiles/
+
+# Or create symlink
+ln -sf $(pwd)/gemma4-turboquant.yaml ~/.hermes/profiles/
+```
+
+### 5. Use with Hermes
+
+```bash
+# Start Hermes with the profile
+hermes --profile gemma4-turboquant
+
+# Or specify profile in Hermes config
+echo "default_profile: gemma4-turboquant" >> ~/.hermes/config.yaml
+```
+
+## Profile Configuration
+
+The profile includes:
+
+- **Primary Provider:** Local llama.cpp server with TurboQuant
+- **Fallback Providers:** Ollama (local), OpenAI (cloud)
+- **TurboQuant Settings:**
+  - `kv_type`: turbo4 (4-bit compression)
+  - `layer_adaptive_mode`: 7 (best quality/compression ratio)
+  - `max_context`: 128K tokens
+
+## Performance Expectations
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| KV Memory Savings | 73% | Measured on M3 Max |
+| Prompt Processing | ~1% overhead | vs FP16 baseline |
+| Generation Speed | ~11% overhead | vs FP16 baseline |
+| Max Context (36GB) | 128K | Comfortable with 7.6GB headroom |
+
+## Customization
+
+### Adjust Compression Level
+
+```yaml
+turboquant:
+  kv_type: "turbo3"  # Lower compression, faster
+  # or
+  kv_type: "turbo2"  # Minimal compression, fastest
+```
+
+### Disable Per-Layer Adaptive
+
+```yaml
+turboquant:
+  layer_adaptive_mode: 0  # Uniform quantization
+```
+
+### Use Asymmetric K/V
+
+For better quality on sensitive models:
+
+```bash
+# Start server with asymmetric K/V
+llama-server -m model.gguf --port 8081 -ctk q8_0 -ctv turbo4 -c 131072
+```
+
+## Troubleshooting
+
+### Server Won't Start
+
+1. Check if port 8081 is available: `lsof -i :8081`
+2. Verify model path is correct
+3. Ensure TurboQuant branch is checked out
+
+### Poor Generation Quality
+
+1. Try `turbo3` instead of `turbo4`
+2. Disable per-layer adaptive (mode 0)
+3. Use asymmetric K/V: `-ctk q8_0 -ctv turbo4`
+
+### High Memory Usage
+
+1. Reduce context length: `-c 65536` (64K)
+2. Check `TURBO_LAYER_ADAPTIVE` is set
+3. Monitor with: `vmmap --summary $(pgrep llama-server)`
+
+## References
+
+- [TurboQuant Build Spec](../BUILD-SPEC.md)
+- [Phase 1 Report](../PHASE1-REPORT.md)
+- [Full Knowledge Transfer](../FULL-REPORT.md)
+- [llama.cpp TurboQuant Fork](https://github.com/TheTom/llama-cpp-turboquant)

profiles/hermes-profile-gemma4-turboquant.yaml

@@ -0,0 +1,169 @@
+# Hermes Profile: Gemma 4 + TurboQuant KV Cache Compression
+# For use with local llama.cpp server running TurboQuant-enabled inference
+# Drop into ~/.hermes/profiles/gemma4-turboquant.yaml
+
+profile:
+  name: "gemma4-turboquant"
+  version: "1.0.0"
+  description: "Gemma 4 model with TurboQuant KV cache compression for extended context on Apple Silicon"
+
+# Primary provider: local llama.cpp server with TurboQuant
+providers:
+  primary:
+    type: "llama.cpp"
+    name: "local-turboquant"
+    endpoint: "http://localhost:8081"
+    api_path: "/v1/chat/completions"
+    timeout_ms: 120000
+    
+    # Model configuration
+    model:
+      name: "gemma-4"
+      path: "/path/to/gemma-4-q4_k_m.gguf"  # Update with actual model path
+      
+    # TurboQuant KV cache compression settings
+    turboquant:
+      enabled: true
+      kv_type: "turbo4"  # Options: turbo2, turbo3, turbo4 (4-bit recommended)
+      layer_adaptive_mode: 7  # Per-layer adaptive quantization (0-7, 7=best quality/ratio)
+      
+    # Context and memory settings
+    context:
+      max_tokens: 131072  # 128K context with TurboQuant compression
+      batch_size: 512
+      
+    # Generation parameters
+    generation:
+      temperature: 0.7
+      top_p: 0.9
+      top_k: 40
+      repeat_penalty: 1.1
+      frequency_penalty: 0.0
+      presence_penalty: 0.0
+      
+    # Server startup command (for reference)
+    server_command: |
+      export TURBO_LAYER_ADAPTIVE=7
+      llama-server \
+        -m /path/to/gemma-4-q4_k_m.gguf \
+        --port 8081 \
+        -ctk turbo4 -ctv turbo4 \
+        -c 131072 \
+        --host 0.0.0.0
+
+  # Fallback provider 1: Ollama (standard, no TurboQuant)
+  fallback_1:
+    type: "ollama"
+    name: "ollama-gemma4"
+    endpoint: "http://localhost:11434"
+    api_path: "/api/chat"
+    timeout_ms: 120000
+    
+    model:
+      name: "gemma4:latest"
+      
+    generation:
+      temperature: 0.7
+      top_p: 0.9
+      top_k: 40
+
+  # Fallback provider 2: OpenAI-compatible API (cloud backup)
+  fallback_2:
+    type: "openai"
+    name: "openai-backup"
+    endpoint: "https://api.openai.com"
+    api_path: "/v1/chat/completions"
+    timeout_ms: 60000
+    
+    model:
+      name: "gpt-4"
+      
+    generation:
+      temperature: 0.7
+      max_tokens: 4096
+
+# Performance and monitoring
+performance:
+  # Memory management for TurboQuant
+  memory:
+    max_gpu_memory_gb: 28  # Leave headroom on 36GB M3 Max
+    kv_cache_compression: "turbo4"
+    estimated_savings: "73%"  # TurboQuant delivers ~73% KV memory savings
+    
+  # Benchmarking integration
+  benchmarks:
+    enabled: true
+    metrics:
+      - "tokens_per_second"
+      - "time_to_first_token"
+      - "peak_memory_usage"
+      - "perplexity"
+
+# Quality validation
+quality:
+  # Test prompts for quality comparison
+  test_prompts:
+    enabled: true
+    prompt_file: "benchmarks/prompts.json"
+    
+  # Perplexity testing
+  perplexity:
+    enabled: true
+    corpus: "wikitext-2-raw"
+    context_lengths: [8192, 32768, 65536, 131072]
+
+# Environment variables (applied when using this profile)
+environment:
+  TURBO_LAYER_ADAPTIVE: "7"  # Per-layer adaptive quantization mode
+  GGML_METAL_DEBUG: "0"  # Disable Metal debug in production
+  OMP_NUM_THREADS: "8"  # Optimize for M3 Max performance cores
+
+# Logging and diagnostics
+logging:
+  level: "info"
+  metrics_interval_seconds: 60
+  log_token_speed: true
+  log_memory_usage: true
+
+# Notes for deployment
+notes:
+  deployment: |
+    1. Ensure llama.cpp fork with TurboQuant is built:
+       cd /path/to/llama-cpp-turboquant
+       git checkout feature/turboquant-kv-cache
+       cmake -B build -DGGML_METAL=ON -DCMAKE_BUILD_TYPE=Release
+       cmake --build build -j$(sysctl -n hw.ncpu)
+    
+    2. Start the server:
+       export TURBO_LAYER_ADAPTIVE=7
+       ./build/bin/llama-server \
+         -m /path/to/gemma-4-q4_k_m.gguf \
+         --port 8081 \
+         -ctk turbo4 -ctv turbo4 \
+         -c 131072 \
+         --host 0.0.0.0
+    
+    3. Verify server is running:
+       curl http://localhost:8081/v1/models
+    
+    4. Copy this profile to Hermes:
+       cp hermes-profile-gemma4-turboquant.yaml ~/.hermes/profiles/
+    
+  performance_notes: |
+    TurboQuant delivers:
+    - 73% KV cache memory savings
+    - 1% prompt processing overhead
+    - 11% generation overhead
+    - Enables 128K context on 36GB hardware
+    
+    With TurboQuant on Gemma 4 (estimated):
+    - Model weights: ~16GB at Q4_K_M
+    - KV cache at 128K: ~5GB (vs ~20GB without compression)
+    - Total memory: ~23GB (fits comfortably in 31GB budget)
+    
+  troubleshooting: |
+    - If generation speed is slow, try turbo3 instead of turbo4
+    - If quality issues, disable per-layer adaptive (set mode to 0)
+    - For maximum quality on sensitive layers, use asymmetric K/V:
+      -ctk q8_0 -ctv turbo4
+    - Monitor memory with: vmmap --summary $(pgrep llama-server)