feat: add Timmy Gemma4 Mac wiring helper (#543)

docs/LAB-003-battery-disconnect-install.md

@@ -1,281 +0,0 @@
-# LAB-003: Truck Battery Disconnect Switch Installation
-
-**Issue:** [timmy-home#528](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/528)  
-**Objective:** Eliminate parasitic battery drain via proper disconnect switch installation  
-**Status:** Planning Complete — Ready for Execution
-
----
-
-## Problem Statement
-
-Parasitic battery drain is killing the truck battery when parked. This is critical for operational mobility in a rural location where the truck is essential for:
-- Supply runs to Newport/Claremont
-- Emergency egress
-- Equipment transport
-
-The battery has likely been damaged from repeated deep discharges and may need replacement.
-
----
-
-## Pre-Installation Checklist
-
-### Diagnostic Steps (Do These First)
-
-1. **Verify parasitic drain with multimeter:**
-   - Set multimeter to DC Amps (10A scale)
-   - Disconnect negative battery terminal
-   - Connect multimeter in series between battery negative and cable
-   - Normal drain: <50mA (0.05A)
-   - Problem drain: >100mA (0.1A)
-   - Record reading: __________ mA
-
-2. **Identify the culprit (if drain is high):**
-   - While monitoring current, pull fuses one at a time
-   - When current drops, you've found the circuit
-   - Common culprits: aftermarket radio, alarm system, interior lights, OBD-II tracker
-
-3. **Test battery health:**
-   - With engine off, battery voltage should be ~12.6V
-   - With engine running, alternator should show ~13.7-14.7V
-   - If voltage <12.4V when "fully charged," battery is degraded
-
----
-
-## Shopping List
-
-### Required Items
-
-| Item | Purpose | Est. Cost | Stores |
-|------|---------|-----------|--------|
-| Battery disconnect switch (side-post or top-post) | Isolate battery when parked | $8-15 | AutoZone, Advance, O'Reilly, NAPA |
-| Terminal shim/post riser (if needed) | Ensure proper terminal clearance | $3-8 | Same as above |
-| Dielectric grease | Prevent corrosion on terminals | $3-5 | Same as above |
-| Battery terminal cleaner brush | Clean posts before install | $2-4 | Same as above |
-| **Total Estimated** | | **$15-30** | |
-
-### Product Recommendations
-
-#### Option 1: Top Terminal Post Mount (Most Common)
-- **Recommended:** Battery Doctor Knife Switch #20138 (Advance Auto)
-  - $12-15
-  - 250A continuous, 1000A surge
-  - Easy quarter-turn operation
-  - No tools needed to operate
-
-- **Alternative:** EverStart Battery Disconnect Switch (Walmart/AutoZone)
-  - $8-12
-  - 125A continuous
-  - Twist-knob style
-
-#### Option 2: Side Terminal Mount (GM Vehicles)
-- **Recommended:** Battery Doctor Side Terminal Switch #20140
-  - $12-18
-  - Designed for GM-style side terminals
-  - Requires terminal shim for proper fit
-
-#### Option 3: Quick-Disconnect (Side Post with Cable)
-- **Recommended:** Quick Cable Battery Disconnect #5091
-  - $10-15
-  - Works with existing cable ends
-  - Marine-grade (good for NH weather)
-
-### Store Locations (Newport/Claremont Area)
-
-**AutoZone — Newport**
-- 65 Main St, Newport, NH 03773
-- (603) 863-5040
-- Hours: M-Sat 7:30AM-9PM, Sun 9AM-8PM
-
-**Advance Auto Parts — Newport**
-- 71 Main St, Newport, NH 03773
-- (603) 863-2860
-- Hours: M-Sat 7:30AM-9PM, Sun 9AM-7PM
-
-**O'Reilly Auto Parts — Claremont**
-- 385 Washington St, Claremont, NH 03743
-- (603) 542-4635
-- Hours: M-Sat 7:30AM-9PM, Sun 9AM-8PM
-
-**NAPA Auto Parts — Newport**
-- 29 John Stark Hwy, Newport, NH 03773
-- (603) 863-5500
-- Hours: M-F 7:30AM-6PM, Sat 7:30AM-4PM, Sun Closed
-
----
-
-## Installation Procedure
-
-### Tools Required
-- 10mm wrench (for most battery terminals)
-- 13mm wrench (if GM side terminals)
-- Wire brush or terminal cleaner
-- Shop rags
-- Optional: zip ties for cable management
-
-### Step-by-Step Installation
-
-1. **Safety First**
-   - Park on level ground
-   - Engage parking brake
-   - Remove keys from ignition
-   - Wear safety glasses
-
-2. **Disconnect Battery**
-   - **CRITICAL:** Disconnect NEGATIVE (-) terminal FIRST
-   - This prevents short circuits if wrench touches frame
-   - Loosen 10mm nut, wiggle terminal off post
-   - Tuck cable away so it can't touch battery post
-
-3. **Clean Terminals**
-   - Use terminal brush to clean inside of cable clamp
-   - Clean battery post until shiny
-   - Apply thin layer of dielectric grease to post
-
-4. **Install Disconnect Switch**
-
-   **For Top Post Batteries:**
-   - Remove battery cable end from switch (if pre-attached)
-   - Slide switch onto battery negative post
-   - Re-attach cable to other side of switch
-   - Tighten securely (don't overtighten — battery posts strip easily)
-
-   **For Side Terminal (GM) Batteries:**
-   - May need terminal shim/post riser for clearance
-   - Install shim on negative side terminal
-   - Mount switch to shim
-   - Connect cable to switch
-
-   **For Cable-End Style:**
-   - Cut existing negative cable near battery (leave enough slack)
-   - Strip 1/2" of insulation from both ends
-   - Install in quick-disconnect connector
-   - Crimp or bolt securely per manufacturer instructions
-
-5. **Test Installation**
-   - Switch should rotate/turn smoothly
-   - No binding or interference with battery hold-down
-   - Cable has enough slack for switch operation
-   - Switch in "ON" position: truck electronics work
-   - Switch in "OFF" position: no power to truck
-
-6. **Reconnect and Verify**
-   - Switch to ON position
-   - Attempt to start truck — should start normally
-   - Check all electronics function
-   - Switch to OFF position
-   - Verify no interior lights, radio, etc.
-
----
-
-## Testing Protocol
-
-### Immediate Test (Same Day)
-- [ ] Start truck with switch ON — engine starts normally
-- [ ] Turn switch OFF while running — engine dies (expected)
-- [ ] Switch OFF, wait 30 seconds, attempt start — no response (expected)
-- [ ] Switch ON, attempt start — starts normally
-
-### Overnight Test (Critical)
-- [ ] Park truck with switch in OFF position
-- [ ] Note battery voltage: __________ V
-- [ ] Wait 24 hours
-- [ ] Next day, switch ON, attempt start
-- [ ] Record result: □ Started normally  □ Slow crank  □ No start
-- [ ] If started, check voltage: __________ V
-
-### 48-Hour Test (If Battery Healthy)
-- [ ] Repeat overnight test with 48-hour duration
-- [ ] If truck starts normally, installation is successful
-- [ ] If truck fails to start, battery replacement needed
-
----
-
-## If Battery Needs Replacement
-
-### Symptoms of Bad Battery
-- Voltage <12.4V after "charging" overnight
-- Slow cranking even with switch disconnected
-- Battery case bulging or terminals corroded
-- Battery >4 years old
-
-### Replacement Battery Shopping
-
-**Common Truck Batteries (Group Size):**
-- Measure existing battery or check current battery label
-- Common truck sizes: Group 24F, 27F, 31, 65, 78
-
-**Recommended:**
-- **DieHard Platinum AGM** (Advance Auto) — $200-250
-  - Best cold cranking amps (CCA) for NH winters
-  - AGM handles deep discharges better
-  - 3-year full replacement warranty
-
-- **EverStart Maxx** (Walmart) — $100-150
-  - Budget option
-  - Check CCA rating matches or exceeds old battery
-
-- **Optima YellowTop** (Pep Boys/Amazon) — $300+
-  - Deep cycle + starting
-  - Best for vehicles with parasitic drain issues
-  - Handles repeated discharge cycles
-
----
-
-## Documentation Requirements
-
-Per issue #528 acceptance criteria, upload to Gitea:
-
-- [ ] Photo of installed disconnect switch (close-up)
-- [ ] Photo of receipt from parts store
-- [ ] Photo of truck odometer (optional, for record)
-- [ ] Note of test results (overnight start success/failure)
-- [ ] Note of battery voltage readings (before/after)
-
-Upload via:
-1. Open issue #528 in browser
-2. Comment with photos attached
-3. Check off acceptance criteria
-
----
-
-## Troubleshooting
-
-| Problem | Cause | Solution |
-|---------|-------|----------|
-| Switch won't tighten on post | Wrong terminal type | Get side-terminal adapter or different switch style |
-| Switch hits battery hold-down | Clearance issue | Add terminal shim to raise switch, or relocate hold-down |
-| Cable too short | Switch adds height | Get battery cable extension or longer replacement cable |
-| Still drains with switch OFF | Switch installed on wrong terminal | Move to NEGATIVE terminal only |
-| Switch gets hot | Loose connection | Tighten terminal nuts; check for corrosion |
-| Truck won't start even with switch ON | Battery too dead | Jump start, then evaluate if battery needs replacement |
-
----
-
-## Cold Weather Considerations (NH)
-
-- Batteries lose ~50% capacity at 0°F
-- Disconnect switch prevents drain but doesn't prevent cold damage
-- If storing truck long-term:
-  - Switch to OFF
-  - Consider battery maintainer (trickle charger)
-  - Or remove battery and store in heated space
-
----
-
-## Summary
-
-This installation is straightforward and should take 30-60 minutes including store run. The key steps:
-
-1. **Diagnose first** — verify parasitic drain, check battery health
-2. **Buy the right switch** — match your battery terminal type (top vs side)
-3. **Install on NEGATIVE terminal only** — this is critical for safety
-4. **Test thoroughly** — overnight test proves the fix worked
-5. **Document** — photos and receipts to close the issue
-
-**Estimated total time:** 2-3 hours (including store run)  
-**Estimated cost:** $15-30 (switch only) or $100-300 (if battery replacement needed)
-
----
-
-*Prepared for: timmy-home#528*  
-*Last updated: 2026-04-22*

docs/LAB-003-verification-template.md

@@ -1,109 +0,0 @@
-# LAB-003 Verification Report Template
-
-**Issue:** [timmy-home#528](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/528)  
-**Date:** __________  
-**Technician:** __________
-
----
-
-## Pre-Installation Diagnostics
-
-| Test | Reading | Normal Range | Status |
-|------|---------|--------------|--------|
-| Battery Voltage (engine off) | _____ V | 12.4-12.7V | □ Pass □ Fail |
-| Parasitic Current | _____ mA | <50mA | □ Pass □ Fail |
-| Battery Voltage (engine running) | _____ V | 13.7-14.7V | □ Pass □ Fail |
-
-**Battery Health Assessment:** □ Good □ Fair □ Replace
-
----
-
-## Parts Purchased
-
-| Item | Store | Cost |
-|------|-------|------|
-| Battery Disconnect Switch | _________ | $_____ |
-| Dielectric Grease | _________ | $_____ |
-| Terminal Cleaner | _________ | $_____ |
-| Other: _________ | _________ | $_____ |
-| **Total** | | **$_____** |
-
----
-
-## Installation Checklist
-
-- [ ] Negative terminal disconnected first
-- [ ] Terminals cleaned
-- [ ] Dielectric grease applied
-- [ ] Switch installed on NEGATIVE terminal
-- [ ] All connections tight
-- [ ] Switch operates smoothly (no tools needed)
-- [ ] No interference with hood/battery hold-down
-
----
-
-## Post-Installation Tests
-
-### Immediate Tests
-- [ ] Truck starts with switch ON
-- [ ] No power with switch OFF
-- [ ] All electronics function normally (switch ON)
-
-### 24-Hour Test
-- [ ] Parked with switch OFF for 24+ hours
-- [ ] Truck started normally next day
-- [ ] Battery voltage before test: _____ V
-- [ ] Battery voltage after test: _____ V
-
-### 48-Hour Test (if applicable)
-- [ ] Parked with switch OFF for 48+ hours
-- [ ] Truck started normally
-
----
-
-## Photos Required
-
-Upload these to issue #528:
-
-- [ ] Photo of installed disconnect switch (close-up)
-- [ ] Photo of receipt from parts store
-- [ ] Photo showing switch in OFF position
-- [ ] Photo of truck dashboard (optional, for records)
-
----
-
-## Results Summary
-
-| Acceptance Criterion | Status |
-|---------------------|--------|
-| Disconnect switch installed and physically secure | □ Pass □ Fail |
-| Truck starts reliably after 24+ hours with switch disconnected | □ Pass □ Fail |
-| No special tools required to operate the disconnect | □ Pass □ Fail |
-| Receipt uploaded to issue | □ Pass □ Fail |
-
-**Overall Status:** □ Complete - All criteria met  
-□ Partial - See notes  
-□ Failed - Requires follow-up
-
----
-
-## Notes / Issues Encountered
-
-_________________________________________________________________
-
-_________________________________________________________________
-
-_________________________________________________________________
-
----
-
-## Follow-up Actions (if needed)
-
-- [ ] Replace battery (if tests failed)
-- [ ] Exchange switch for different style (if fitment issue)
-- [ ] Troubleshoot remaining parasitic drain
-- [ ] Other: _____________________________________________
-
----
-
-*Fill out this template during installation and upload to issue #528*

scripts/README_big_brain.md

@@ -62,6 +62,24 @@ Writes:
 
 ## Usage
 
+### Timmy Mac wiring helper
+
+Use the dedicated Timmy helper when you want to wire a real RunPod or Vertex-style endpoint into the local Mac Hermes config:
+
+```bash
+python3 scripts/timmy_gemma4_mac.py --base-url https://your-openai-bridge.example/v1 --write-config
+python3 scripts/timmy_gemma4_mac.py --vertex-base-url https://your-vertex-bridge.example --write-config
+python3 scripts/timmy_gemma4_mac.py --pod-id <runpod-id> --write-config --verify-chat
+```
+
+The helper writes to `~/.hermes/config.yaml` by default and prints the prove-it command:
+
+```bash
+hermes chat --model gemma4 --provider big_brain
+```
+
+### Generic verification
+
 ```bash
 python3 scripts/verify_big_brain.py
 python3 scripts/big_brain_manager.py

scripts/lab_003_battery_disconnect.sh

@@ -1,215 +0,0 @@
-#!/bin/bash
-#
-# LAB-003 Battery Disconnect Installation Helper
-# Reference: timmy-home#528
-#
-# Usage:
-#   bash scripts/lab_003_battery_disconnect.sh diagnose    # Test battery before install
-#   bash scripts/lab_003_battery_disconnect.sh checklist   # Print installation checklist
-#   bash scripts/lab_003_battery_disconnect.sh verify      # Post-install verification
-#
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-LOG_FILE="$SCRIPT_DIR/../logs/lab_003_$(date +%Y%m%d_%H%M%S).log"
-ISSUE_URL="https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/528"
-
-echo "=== LAB-003: Battery Disconnect Switch Installation ==="
-echo "Issue: $ISSUE_URL"
-echo ""
-
-mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
-
-log() {
-    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE" 2>/dev/null || echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
-}
-
-diagnose() {
-    log "=== Battery Diagnosis ==="
-    echo ""
-    echo "This will help determine if you need a new battery or just the disconnect switch."
-    echo ""
-    
-    echo "Step 1: Check battery voltage with multimeter"
-    echo "  - Set multimeter to DC Volts (20V scale)"
-    echo "  - Red probe to battery positive (+)"
-    echo "  - Black probe to battery negative (-)"
-    echo ""
-    read -p "Enter voltage reading (e.g., 12.6): " voltage
-    log "Battery voltage: ${voltage}V"
-    
-    if (( $(echo "$voltage >= 12.6" | bc -l) )); then
-        echo "✓ Battery voltage is GOOD (≥12.6V)"
-        log "Battery voltage GOOD"
-    elif (( $(echo "$voltage >= 12.4" | bc -l) )); then
-        echo "⚠ Battery voltage is FAIR (12.4-12.5V) - may need replacement soon"
-        log "Battery voltage FAIR"
-    else
-        echo "✗ Battery voltage is LOW (<12.4V) - likely needs replacement"
-        log "Battery voltage LOW - replacement recommended"
-    fi
-    
-    echo ""
-    echo "Step 2: Check for parasitic drain"
-    echo "  - Set multimeter to DC Amps (10A scale)"
-    echo "  - Disconnect negative battery cable"
-    echo "  - Connect multimeter between battery negative post and cable"
-    echo "  - Wait 2 minutes for modules to sleep"
-    echo ""
-    read -p "Enter current reading in milliamps (e.g., 50): " current
-    log "Parasitic current: ${current}mA"
-    
-    if (( $(echo "$current <= 50" | bc -l) )); then
-        echo "✓ Parasitic drain is NORMAL (≤50mA)"
-        log "Parasitic drain NORMAL"
-        echo ""
-        echo "NOTE: Normal drain means the disconnect switch may not be necessary"
-        echo "      unless you're storing the truck for weeks at a time."
-    elif (( $(echo "$current <= 100" | bc -l) )); then
-        echo "⚠ Parasitic drain is ELEVATED (50-100mA)"
-        log "Parasitic drain ELEVATED"
-        echo "Disconnect switch will help prevent dead battery."
-    else
-        echo "✗ Parasitic drain is HIGH (>100mA)"
-        log "Parasitic drain HIGH - disconnect switch highly recommended"
-        echo ""
-        echo "You definitely need the disconnect switch!"
-    fi
-    
-    echo ""
-    log "Diagnosis complete. Log saved to: $LOG_FILE"
-}
-
-checklist() {
-    cat << 'EOF'
-=== LAB-003 Installation Checklist ===
-
-BEFORE YOU GO:
-□ Determine battery terminal type (top post vs side terminal)
-□ Measure battery group size (look for label like "Group 24F")
-□ Check if you have 10mm and 13mm wrenches
-□ Verify multimeter has DC Volts and DC Amps capability
-
-AT THE STORE:
-□ Purchase battery disconnect switch (match your terminal type)
-□ Purchase dielectric grease
-□ Purchase terminal cleaner brush (if you don't have one)
-□ Get receipt for documentation
-
-INSTALLATION:
-□ Park on level ground, engage parking brake
-□ Disconnect NEGATIVE (-) terminal first
-□ Clean terminals with wire brush
-□ Apply dielectric grease
-□ Install switch on NEGATIVE terminal
-□ Reconnect and test operation
-
-TESTING:
-□ Switch ON: truck starts normally
-□ Switch OFF: no power to truck
-□ Overnight test: switch OFF, verify start next day
-□ Document with photos
-□ Upload photos to issue #528
-
-TROUBLESHOOTING:
-□ If switch doesn't fit: wrong terminal type - exchange at store
-□ If still drains overnight: battery needs replacement
-□ If slow crank with new switch: battery degraded - replace
-
-EOF
-}
-
-verify() {
-    log "=== Post-Installation Verification ==="
-    echo ""
-    echo "Post-installation tests. Run these AFTER installing the disconnect switch."
-    echo ""
-    
-    read -p "Test 1 - Can you start the truck with the switch ON? (y/n): " t1
-    if [[ "$t1" == "y" ]]; then
-        log "Test 1 PASSED: Truck starts with switch ON"
-        echo "✓ Test 1 PASSED"
-    else
-        log "Test 1 FAILED: Truck won't start with switch ON"
-        echo "✗ Test 1 FAILED - Check installation and battery"
-    fi
-    
-    echo ""
-    read -p "Test 2 - With truck OFF and switch OFF, do interior lights/radio work? (y/n): " t2
-    if [[ "$t2" == "n" ]]; then
-        log "Test 2 PASSED: No power with switch OFF"
-        echo "✓ Test 2 PASSED"
-    else
-        log "Test 2 FAILED: Power still on with switch OFF"
-        echo "✗ Test 2 FAILED - Switch may be on wrong terminal or defective"
-    fi
-    
-    echo ""
-    read -p "Test 3 - Is the switch easy to operate by hand (no tools needed)? (y/n): " t3
-    if [[ "$t3" == "y" ]]; then
-        log "Test 3 PASSED: Switch operable without tools"
-        echo "✓ Test 3 PASSED"
-    else
-        log "Test 3 WARNING: Switch may require tools"
-        echo "⚠ Test 3 WARNING - Consider a different switch style"
-    fi
-    
-    echo ""
-    echo "=== 24-Hour Test ==="
-    echo "Park truck with switch OFF. Tomorrow, try to start it."
-    echo "Record result in issue #528: $ISSUE_URL"
-    echo ""
-    
-    read -p "Did the 24-hour test pass (truck started normally)? (y/n/skip): " t24
-    case "$t24" in
-        y)
-            log "24-hour test PASSED"
-            echo "✓ Installation SUCCESSFUL!"
-            echo ""
-            echo "Close issue #528 with:"
-            echo "  - Photo of installed switch"
-            echo "  - Photo of receipt"
-            echo "  - Note: '24-hour test passed, truck started normally'"
-            ;;
-        n)
-            log "24-hour test FAILED"
-            echo "✗ Test FAILED - Battery likely needs replacement"
-            echo ""
-            echo "Next steps:"
-            echo "  1. Jump start truck"
-            echo "  2. Drive to store for battery replacement"
-            echo "  3. Reference LAB-003-battery-disconnect-install.md for battery shopping guide"
-            ;;
-        *)
-            log "24-hour test pending"
-            echo "Run this script again after 24 hours with: bash $0 verify"
-            ;;
-    esac
-    
-    echo ""
-    log "Verification complete. Log saved to: $LOG_FILE"
-}
-
-case "${1:-help}" in
-    diagnose)
-        diagnose
-        ;;
-    checklist)
-        checklist
-        ;;
-    verify)
-        verify
-        ;;
-    *)
-        echo "Usage: $0 {diagnose|checklist|verify}"
-        echo ""
-        echo "  diagnose   - Check battery voltage and parasitic drain"
-        echo "  checklist  - Print installation checklist"
-        echo "  verify     - Post-installation verification tests"
-        echo ""
-        echo "Full guide: docs/LAB-003-battery-disconnect-install.md"
-        echo "Issue: $ISSUE_URL"
-        exit 1
-        ;;
-esac

scripts/timmy_gemma4_mac.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Timmy Mac Gemma 4 wiring helper for RunPod / Vertex-style Big Brain providers.
+
+Refs: timmy-home #543
+
+Safe by default:
+- computes a Big Brain base URL from an explicit URL, Vertex bridge URL, or RunPod pod id
+- can provision a RunPod pod when --apply-runpod is used and a token is available
+- can write the resolved endpoint into a Hermes config when --write-config is used
+- can verify an OpenAI-compatible chat endpoint when --verify-chat is used
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+from urllib import request
+
+from scripts.bezalel_gemma4_vps import (
+    DEFAULT_CLOUD_TYPE,
+    DEFAULT_GPU_TYPE,
+    DEFAULT_MODEL,
+    DEFAULT_PROVIDER_NAME,
+    build_runpod_endpoint,
+    deploy_runpod,
+    update_config_text,
+)
+
+DEFAULT_TOKEN_FILE = Path.home() / ".config" / "runpod" / "access_key"
+DEFAULT_CONFIG_PATH = Path.home() / ".hermes" / "config.yaml"
+
+
+def _normalize_openai_base(base_url: str | None) -> str:
+    if not base_url:
+        return ""
+    cleaned = str(base_url).strip().rstrip("/")
+    return cleaned if cleaned.endswith("/v1") else f"{cleaned}/v1"
+
+
+def choose_base_url(*, vertex_base_url: str | None = None, base_url: str | None = None, pod_id: str | None = None) -> str:
+    if vertex_base_url:
+        return _normalize_openai_base(vertex_base_url)
+    if base_url:
+        return _normalize_openai_base(base_url)
+    if pod_id:
+        return build_runpod_endpoint(pod_id)
+    return "https://YOUR_BIG_BRAIN_HOST/v1"
+
+
+def write_config_file(config_path: Path, *, base_url: str, model: str = DEFAULT_MODEL, provider_name: str = DEFAULT_PROVIDER_NAME) -> str:
+    original = config_path.read_text() if config_path.exists() else ""
+    updated = update_config_text(original, base_url=base_url, model=model, provider_name=provider_name)
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(updated)
+    return updated
+
+
+def verify_openai_chat(base_url: str, *, model: str = DEFAULT_MODEL, prompt: str = "Say READY") -> str:
+    payload = json.dumps(
+        {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "stream": False,
+            "max_tokens": 16,
+        }
+    ).encode()
+    req = request.Request(
+        f"{base_url.rstrip('/')}/chat/completions",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with request.urlopen(req, timeout=30) as resp:
+        data = json.loads(resp.read().decode())
+    return data["choices"][0]["message"]["content"]
+
+
+def build_summary(*, base_url: str, model: str, provider_name: str = DEFAULT_PROVIDER_NAME, config_path: Path = DEFAULT_CONFIG_PATH) -> dict[str, Any]:
+    return {
+        "provider_name": provider_name,
+        "base_url": base_url,
+        "model": model,
+        "config_path": str(config_path),
+        "verification_commands": [
+            "python3 scripts/verify_big_brain.py",
+            f"python3 scripts/timmy_gemma4_mac.py --base-url {base_url} --write-config --verify-chat",
+            "hermes chat --model gemma4 --provider big_brain",
+        ],
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Wire a RunPod/Vertex Gemma 4 endpoint into Timmy's Mac Hermes config.")
+    parser.add_argument("--pod-name", default="timmy-gemma4")
+    parser.add_argument("--gpu-type", default=DEFAULT_GPU_TYPE)
+    parser.add_argument("--cloud-type", default=DEFAULT_CLOUD_TYPE)
+    parser.add_argument("--model", default=DEFAULT_MODEL)
+    parser.add_argument("--provider-name", default=DEFAULT_PROVIDER_NAME)
+    parser.add_argument("--token-file", type=Path, default=DEFAULT_TOKEN_FILE)
+    parser.add_argument("--config-path", type=Path, default=DEFAULT_CONFIG_PATH)
+    parser.add_argument("--pod-id", help="Existing RunPod pod id to convert into an OpenAI-compatible base URL")
+    parser.add_argument("--base-url", help="Explicit OpenAI-compatible base URL")
+    parser.add_argument("--vertex-base-url", help="Vertex AI OpenAI-compatible bridge base URL")
+    parser.add_argument("--apply-runpod", action="store_true", help="Provision a RunPod pod using the RunPod GraphQL API")
+    parser.add_argument("--write-config", action="store_true", help="Write the resolved endpoint into --config-path")
+    parser.add_argument("--verify-chat", action="store_true", help="Run a lightweight OpenAI-compatible chat probe")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    summary: dict[str, Any] = {
+        "pod_name": args.pod_name,
+        "gpu_type": args.gpu_type,
+        "cloud_type": args.cloud_type,
+        "model": args.model,
+        "provider_name": args.provider_name,
+        "actions": [],
+    }
+
+    base_url = choose_base_url(vertex_base_url=args.vertex_base_url, base_url=args.base_url, pod_id=args.pod_id)
+
+    if args.apply_runpod:
+        if not args.token_file.exists():
+            raise SystemExit(f"RunPod token file not found: {args.token_file}")
+        api_key = args.token_file.read_text().strip()
+        deployed = deploy_runpod(api_key=api_key, name=args.pod_name, gpu_type=args.gpu_type, cloud_type=args.cloud_type, model=args.model)
+        summary["deployment"] = deployed
+        base_url = deployed["base_url"]
+        summary["actions"].append("deployed_runpod_pod")
+
+    summary.update(build_summary(base_url=base_url, model=args.model, provider_name=args.provider_name, config_path=args.config_path))
+
+    if args.write_config:
+        write_config_file(args.config_path, base_url=base_url, model=args.model, provider_name=args.provider_name)
+        summary["actions"].append("wrote_config")
+
+    if args.verify_chat:
+        summary["verify_response"] = verify_openai_chat(base_url, model=args.model)
+        summary["actions"].append("verified_chat")
+
+    if args.json:
+        print(json.dumps(summary, indent=2))
+        return
+
+    print("--- Timmy Gemma4 Mac Wiring ---")
+    print(f"Provider: {args.provider_name}")
+    print(f"Base URL: {base_url}")
+    print(f"Model: {args.model}")
+    print(f"Config path: {args.config_path}")
+    if "verify_response" in summary:
+        print(f"Verify response: {summary['verify_response']}")
+    if summary["actions"]:
+        print("Actions: " + ", ".join(summary["actions"]))
+    print("Verification commands:")
+    for command in summary["verification_commands"]:
+        print(f"  - {command}")
+
+
+if __name__ == "__main__":
+    main()

tests/test_timmy_gemma4_mac.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPT = ROOT / "scripts" / "timmy_gemma4_mac.py"
+README = ROOT / "scripts" / "README_big_brain.md"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("timmy_gemma4_mac", str(SCRIPT))
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["timmy_gemma4_mac"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+class _FakeResponse:
+    def __init__(self, payload: dict):
+        self._payload = json.dumps(payload).encode()
+
+    def read(self) -> bytes:
+        return self._payload
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return False
+
+
+def test_script_exists() -> None:
+    assert SCRIPT.exists(), "scripts/timmy_gemma4_mac.py must exist"
+
+
+def test_default_paths_target_timmy_mac_hermes() -> None:
+    mod = load_module()
+    assert mod.DEFAULT_CONFIG_PATH == Path.home() / ".hermes" / "config.yaml"
+    assert mod.DEFAULT_TOKEN_FILE == Path.home() / ".config" / "runpod" / "access_key"
+
+
+def test_choose_base_url_prefers_vertex_then_explicit_then_runpod() -> None:
+    mod = load_module()
+    assert mod.choose_base_url(vertex_base_url="https://vertex-proxy.example/v1") == "https://vertex-proxy.example/v1"
+    assert mod.choose_base_url(base_url="https://custom-endpoint/v1") == "https://custom-endpoint/v1"
+    assert mod.choose_base_url(pod_id="abc123") == "https://abc123-11434.proxy.runpod.net/v1"
+
+
+def test_build_summary_includes_prove_it_commands() -> None:
+    mod = load_module()
+    summary = mod.build_summary(base_url="https://vertex-proxy.example/v1", model="gemma4:latest")
+    assert summary["verification_commands"][0] == "python3 scripts/verify_big_brain.py"
+    assert any("hermes chat --model gemma4 --provider big_brain" in cmd for cmd in summary["verification_commands"])
+
+
+def test_verify_openai_chat_targets_chat_completions() -> None:
+    mod = load_module()
+    response_payload = {
+        "choices": [{"message": {"content": "READY"}}]
+    }
+
+    with patch("timmy_gemma4_mac.request.urlopen", return_value=_FakeResponse(response_payload)) as mocked:
+        result = mod.verify_openai_chat("https://vertex-proxy.example/v1", model="gemma4:latest", prompt="say READY")
+
+    assert result == "READY"
+    req = mocked.call_args.args[0]
+    assert req.full_url == "https://vertex-proxy.example/v1/chat/completions"
+
+
+def test_readme_mentions_timmy_mac_wiring_flow() -> None:
+    text = README.read_text(encoding="utf-8")
+    required = [
+        "scripts/timmy_gemma4_mac.py",
+        "--vertex-base-url",
+        "--write-config",
+        "python3 scripts/verify_big_brain.py",
+        "hermes chat --model gemma4 --provider big_brain",
+    ]
+    missing = [item for item in required if item not in text]
+    assert not missing, missing