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

evennia/timmy_world/game.py

@@ -12,29 +12,6 @@ WORLD_DIR = Path('/Users/apayne/.timmy/evennia/timmy_world')
 STATE_FILE = WORLD_DIR / 'game_state.json'
 TIMMY_LOG = WORLD_DIR / 'timmy_log.md'
 
-WORLD_ITEMS = {
-    "foraged key": {"effect": "unlock_tower_cache", "quest_item": True, "consumable": False, "effect_text": "A hidden cache clicks open in the Tower wall."},
-    "seed packet": {"effect": "grow_garden", "quest_item": False, "consumable": True, "effect_text": "Fresh growth pushes through the Garden soil."},
-    "notebook": {"effect": "write_notebook_rule", "quest_item": False, "consumable": False, "effect_text": "A new rule joins the whiteboard in the Tower."},
-    "cloth": {"effect": "patch_bridge", "quest_item": False, "consumable": True, "effect_text": "The Bridge railing is wrapped tight against the weather."},
-    "oil can": {"effect": "stoke_forge", "quest_item": False, "consumable": True, "effect_text": "The Forge fire answers with a hotter glow."},
-    "lantern": {"effect": "light_bridge", "quest_item": False, "consumable": False, "effect_text": "A steady lantern glow cuts through the dark over the Bridge."},
-    "rope spool": {"effect": "secure_bridge", "quest_item": False, "consumable": True, "effect_text": "The Bridge is lashed tight and feels safer underfoot."},
-    "chalk": {"effect": "mark_threshold", "quest_item": False, "consumable": True, "effect_text": "A chalk mark at the Threshold points wanderers home."},
-    "weather vane": {"effect": "read_weather", "quest_item": False, "consumable": False, "effect_text": "The weather vane settles and the coming storm makes sense."},
-    "sunstone": {"effect": "restore_tower_power", "quest_item": False, "consumable": False, "effect_text": "Warm light races through the Tower circuits."},
-    "iron nails": {"effect": "reinforce_bridge", "quest_item": False, "consumable": True, "effect_text": "The Bridge planks are pinned down against the flood."},
-    "river stone": {"effect": "water_garden", "quest_item": False, "consumable": True, "effect_text": "Moisture returns to the Garden beds."},
-}
-
-ROOM_DISCOVERABLES = {
-    "Threshold": ["chalk", "sunstone"],
-    "Tower": ["notebook", "lantern"],
-    "Forge": ["oil can", "iron nails"],
-    "Garden": ["seed packet", "foraged key"],
-    "Bridge": ["cloth", "rope spool", "weather vane", "river stone"],
-}
-
 # ============================================================
 # NARRATIVE ARC — 4 phases that transform the world
 # ============================================================
@@ -166,8 +143,6 @@ class World:
                 "visitors": [],
             },
         }
-        for room_name, items in ROOM_DISCOVERABLES.items():
-            self.rooms[room_name]["discoverables"] = list(items)
         
         # Characters (not NPCs — they have lives)
         self.characters = {
@@ -283,14 +258,6 @@ class World:
             "items_crafted": 0,
             "conflicts_resolved": 0,
             "nights_survived": 0,
-            "bridge_patched": False,
-            "bridge_secured": False,
-            "bridge_reinforced": False,
-            "bridge_lantern_lit": False,
-            "tower_cache_unlocked": False,
-            "threshold_marked": False,
-            "weather_readable": False,
-            "sunstone_socketed": False,
         }
     
     def tick_time(self):
@@ -409,14 +376,6 @@ class World:
                 desc += " Rain mists on the dark water below."
             if len(self.rooms["Bridge"]["carvings"]) > 1:
                 desc += f" There are {len(self.rooms['Bridge']['carvings'])} carvings now."
-            if self.state.get("bridge_patched"):
-                desc += " Cloth bindings keep the railing from splintering."
-            if self.state.get("bridge_secured"):
-                desc += " Rope lines keep the span steady against the flood."
-            if self.state.get("bridge_reinforced"):
-                desc += " Fresh iron nails hold the planks tight."
-            if self.state.get("bridge_lantern_lit"):
-                desc += " A lantern glows warm over the water."
         
         elif room_name == "Tower":
             power = self.state.get("tower_power_low", False)
@@ -425,19 +384,6 @@ class World:
             
             if self.rooms["Tower"]["messages"]:
                 desc += f" The whiteboard holds {len(self.rooms['Tower']['messages'])} rules."
-            if self.state.get("tower_cache_unlocked"):
-                desc += " A hidden cache stands open beneath the whiteboard."
-
-        if room_name == "Threshold" and self.state.get("threshold_marked"):
-            desc += " A chalk arrow points late arrivals toward shelter."
-        if room_name == "Garden" and self.state.get("weather_readable"):
-            desc += " The beds are arranged to catch whatever weather comes next."
-        if room_name == "Tower" and self.state.get("sunstone_socketed"):
-            desc += " A sunstone keeps the room lit with a stubborn amber glow."
-
-        discoverables = room.get("discoverables", [])
-        if discoverables:
-            desc += f" Discoverable items: {', '.join(discoverables)}."
         
         # Who's here
         here = [n for n, c in self.characters.items() if c["room"] == room_name and n != char_name]
@@ -539,10 +485,6 @@ class ActionSystem:
             "cost": 1,
             "description": "Take an item from the room",
         },
-        "use": {
-            "cost": 1,
-            "description": "Use an item from your inventory to change the world",
-        },
         "examine": {
             "cost": 0,
             "description": "Examine something in detail",
@@ -588,13 +530,6 @@ class ActionSystem:
         available.append("rest")
         available.append("examine")
         
-        discoverables = world.rooms[room].get("discoverables", [])
-        for item in discoverables:
-            available.append(f"take:{item}")
-
-        for item in char["inventory"]:
-            available.append(f"use:{item}")
-
         if char["inventory"]:
             available.append("give:item")
         
@@ -1137,76 +1072,6 @@ class GameEngine:
                 f.write(f"\n*Began: {datetime.now().strftime('%Y-%m-%d %H:%M')}*\n\n")
                 f.write("---\n\n")
                 f.write(message + "\n")
-
-    def _take_item(self, item_name, scene):
-        room_name = self.world.characters["Timmy"]["room"]
-        discoverables = self.world.rooms[room_name].get("discoverables", [])
-        if item_name not in discoverables:
-            scene["log"].append(f"There is no {item_name} here.")
-            return
-        discoverables.remove(item_name)
-        self.world.characters["Timmy"]["inventory"].append(item_name)
-        scene["log"].append(f"You take the {item_name}.")
-        if WORLD_ITEMS.get(item_name, {}).get("quest_item"):
-            scene["world_events"].append(f"The {item_name} feels important. It might open a quest route.")
-
-    def _use_item(self, item_name, scene):
-        inventory = self.world.characters["Timmy"]["inventory"]
-        if item_name not in inventory:
-            scene["log"].append(f"You are not carrying {item_name}.")
-            return
-        item = WORLD_ITEMS.get(item_name)
-        if not item:
-            scene["log"].append(f"The {item_name} doesn't seem to do anything.")
-            return
-
-        effect = item["effect"]
-        effect_text = item["effect_text"]
-        if effect == "grow_garden":
-            self.world.rooms["Garden"]["growth"] = min(5, self.world.rooms["Garden"]["growth"] + 2)
-            self.world.state["garden_drought"] = False
-        elif effect == "unlock_tower_cache":
-            self.world.state["tower_cache_unlocked"] = True
-            cache_rule = "Rule: Keys open more than doors when the world trusts you."
-            if cache_rule not in self.world.rooms["Tower"]["messages"]:
-                self.world.rooms["Tower"]["messages"].append(cache_rule)
-        elif effect == "write_notebook_rule":
-            note_rule = f"Rule #{self.world.tick}: A notebook can turn memory into structure."
-            self.world.rooms["Tower"]["messages"].append(note_rule)
-        elif effect == "patch_bridge":
-            self.world.state["bridge_patched"] = True
-            self.world.state["bridge_flooding"] = False
-            self.world.rooms["Bridge"]["weather"] = None
-            self.world.rooms["Bridge"]["rain_ticks"] = 0
-        elif effect == "stoke_forge":
-            self.world.rooms["Forge"]["fire"] = "glowing"
-            self.world.state["forge_fire_dying"] = False
-        elif effect == "light_bridge":
-            self.world.state["bridge_lantern_lit"] = True
-        elif effect == "secure_bridge":
-            self.world.state["bridge_secured"] = True
-            self.world.state["bridge_flooding"] = False
-            self.world.rooms["Bridge"]["weather"] = None
-            self.world.rooms["Bridge"]["rain_ticks"] = 0
-        elif effect == "mark_threshold":
-            self.world.state["threshold_marked"] = True
-        elif effect == "read_weather":
-            self.world.state["weather_readable"] = True
-            self.world.state["garden_drought"] = False
-        elif effect == "restore_tower_power":
-            self.world.state["tower_power_low"] = False
-            self.world.state["sunstone_socketed"] = True
-        elif effect == "reinforce_bridge":
-            self.world.state["bridge_reinforced"] = True
-            self.world.state["bridge_flooding"] = False
-        elif effect == "water_garden":
-            self.world.state["garden_drought"] = False
-            self.world.rooms["Garden"]["growth"] = min(5, self.world.rooms["Garden"]["growth"] + 1)
-
-        scene["log"].append(f"You use the {item_name}. {effect_text}")
-        scene["world_events"].append(effect_text)
-        if item.get("consumable"):
-            inventory.remove(item_name)
     
     def run_tick(self, timmy_action="look"):
         """Run one tick. Return the scene and available choices."""
@@ -1235,7 +1100,7 @@ class GameEngine:
         action_costs = {
             "move": 2, "tend_fire": 3, "write_rule": 2, "carve": 2,
             "plant": 2, "study": 2, "forge": 3, "help": 2, "speak": 1,
-            "listen": 0, "rest": -2, "examine": 0, "give": 0, "take": 1, "use": 1,
+            "listen": 0, "rest": -2, "examine": 0, "give": 0, "take": 1,
         }
         
         # Extract action name
@@ -1495,17 +1360,9 @@ class GameEngine:
         elif timmy_action == "examine":
             room = self.world.characters["Timmy"]["room"]
             room_data = self.world.rooms[room]
-            items = room_data.get("items", []) + room_data.get("discoverables", [])
+            items = room_data.get("items", [])
             scene["log"].append(f"You examine The {room}. You see: {', '.join(items) if items else 'nothing special'}")
         
-        elif timmy_action.startswith("take:"):
-            item_name = timmy_action.split(":", 1)[1]
-            self._take_item(item_name, scene)
-
-        elif timmy_action.startswith("use:"):
-            item_name = timmy_action.split(":", 1)[1]
-            self._use_item(item_name, scene)
-        
         elif timmy_action.startswith("help:"):
             # Help increases trust
             target_name = timmy_action.split(":")[1]

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/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

tests/test_tower_game_items.py

@@ -1,58 +0,0 @@
-from importlib.util import module_from_spec, spec_from_file_location
-from pathlib import Path
-import unittest
-
-
-ROOT = Path(__file__).resolve().parent.parent
-GAME_PATH = ROOT / "evennia" / "timmy_world" / "game.py"
-
-
-def load_game_module():
-    spec = spec_from_file_location("tower_game_items", GAME_PATH)
-    module = module_from_spec(spec)
-    assert spec.loader is not None
-    spec.loader.exec_module(module)
-    module.random.seed(0)
-    return module
-
-
-class TestTowerGameWorldItems(unittest.TestCase):
-    def test_world_has_ten_unique_items_and_a_quest_item(self):
-        module = load_game_module()
-        world = module.World()
-
-        room_items = {
-            item
-            for room in world.rooms.values()
-            for item in room.get("discoverables", [])
-        }
-
-        self.assertGreaterEqual(len(room_items), 10)
-        self.assertIn("foraged key", room_items)
-        self.assertTrue(module.WORLD_ITEMS["foraged key"]["quest_item"])
-
-    def test_items_change_world_state_when_used(self):
-        module = load_game_module()
-        engine = module.GameEngine()
-        engine.start_new_game()
-        engine.world.characters["Timmy"]["energy"] = 10
-        engine.world.characters["Timmy"]["room"] = "Garden"
-
-        initial_growth = engine.world.rooms["Garden"]["growth"]
-        engine.run_tick("take:seed packet")
-        use_seed = engine.run_tick("use:seed packet")
-
-        self.assertGreater(engine.world.rooms["Garden"]["growth"], initial_growth)
-        self.assertNotIn("seed packet", engine.world.characters["Timmy"]["inventory"])
-        self.assertTrue(any("garden" in line.lower() for line in use_seed["world_events"] + use_seed["log"]))
-
-        engine.world.characters["Timmy"]["energy"] = 10
-        engine.run_tick("take:foraged key")
-        use_key = engine.run_tick("use:foraged key")
-
-        self.assertTrue(engine.world.state["tower_cache_unlocked"])
-        self.assertTrue(any("cache" in line.lower() or "quest" in line.lower() for line in use_key["world_events"] + use_key["log"]))
-
-
-if __name__ == "__main__":
-    unittest.main()