Add mock mode feature to README

Author: haasonsaas

README.md

@@ -91,12 +91,18 @@ This project contains two main components:
 
 Try the minimal working demo (uses 20 sample QA pairs and simulated evaluation):
 
+**Option 1: Mock Mode (No API Key Required)**
+```bash
+./run_demo.sh  # Automatically uses mock mode if no API key
+```
+
+**Option 2: Real Tinker Infrastructure**
 ```bash
 export TINKER_API_KEY=sk-...  # Your Tinker API key
 ./run_demo.sh
 ```
 
-This will run 1-3 training rounds, automatically adjusting the learning rate and triggering Round 2 when scores fall below threshold (0.75). Perfect for understanding the loop before customizing it.
+This will run 1-3 training rounds, automatically adjusting the learning rate and triggering Round 2 when scores fall below threshold (0.75). Mock mode simulates training locally without cloud calls—perfect for understanding the loop before using real infrastructure.
 
 See [DEMO.md](DEMO.md) for a detailed walkthrough of what happens during the demo run.
 

data_loader.py

@@ -6,12 +6,21 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-try:
-    from tinker import types
-    from tinker_cookbook import renderers
-except ImportError:
-    types = None
+import os
+
+USE_MOCK = os.getenv("TINKER_MOCK", "0") == "1"
+
+if USE_MOCK:
+    from mock_tinker import MockTypes
+    types = MockTypes
     renderers = None
+else:
+    try:
+        from tinker import types
+        from tinker_cookbook import renderers
+    except ImportError:
+        types = None
+        renderers = None
 
 
 class DataLoader:
@@ -111,7 +120,7 @@ def prepare_training_data(
         Returns:
             List of tinker.types.Datum objects with proper loss masking.
         """
-        if types is None:
+        if types is None and not USE_MOCK:
             raise ImportError("tinker package required for data preparation")
 
         raw_examples = self.load_jsonl(train_file)

mock_checkpoints/round_1.json

@@ -0,0 +1 @@
+{"name": "round_1", "mock": true}

mock_checkpoints/round_2.json

@@ -0,0 +1 @@
+{"name": "round_2", "mock": true}

mock_tinker.py

@@ -64,14 +64,12 @@ async def forward_backward_async(self, datums: List[Any], loss_fn: str = "cross_
         await asyncio.sleep(0.01)
         self.step_count += 1
         self.current_loss *= 0.95
+        current_loss_value = self.current_loss
 
         class AsyncFuture:
-            async def __await__(self):
-                return {"loss": self.current_loss}
-            
             def __await__(self):
                 async def _wait():
-                    return {"loss": self.current_loss}
+                    return {"loss": current_loss_value}
                 return _wait().__await__()
 
         return AsyncFuture()

trainer_with_eval.py

@@ -242,8 +242,8 @@ async def async_main(config_path: str) -> None:
 
     config = load_and_validate_config(config_path)
 
-    if tinker is None:
-        raise ImportError("The `tinker` package is not installed.  Please install it via `pip install tinker`.")
+    if tinker is None and not USE_MOCK:
+        raise ImportError("The `tinker` package is not installed. Please install it via `pip install tinker` or run in mock mode with TINKER_MOCK=1.")
 
     service_client = tinker.ServiceClient()
     base_model = config.base_model