Disable llama.cpp schema grammar by default

.env.example

@@ -15,8 +15,9 @@ PARSER_LOG_PARSED_JSON=0
 # LLAMA_CPP_MODEL_REPO=unsloth/Qwen3-1.7B-GGUF
 # LLAMA_CPP_MODEL_FILE=Qwen3-1.7B-Q4_K_M.gguf
 # LLAMA_CPP_MAX_TOKENS=384
-# LLAMA_CPP_N_CTX=2048
+# LLAMA_CPP_N_CTX=4096
 # LLAMA_CPP_N_THREADS=2
+# LLAMA_CPP_USE_GRAMMAR=0
 
 # Optional Hugging Face Dataset storage.
 # Keep real tokens in your local .env or Hugging Face Space secrets.

DECISIONS.md

@@ -91,9 +91,12 @@ with a one-line note on why.
   configured with `PARSER_BACKEND=llama_cpp`,
   `LLAMA_CPP_MODEL_REPO=unsloth/Qwen3-1.7B-GGUF`,
   `LLAMA_CPP_MODEL_FILE=Qwen3-1.7B-Q4_K_M.gguf`, `LLAMA_CPP_MAX_TOKENS=384`,
-  `LLAMA_CPP_N_CTX=2048`, and a Space-specific `LLAMA_CPP_N_THREADS`. This replaces the
-  slow CPU Transformers runtime. The Transformers backend remains only as an explicit
-  local experiment/fallback path and is not installed by the default requirements.
+  `LLAMA_CPP_N_CTX=4096`, a Space-specific `LLAMA_CPP_N_THREADS`, and
+  `LLAMA_CPP_USE_GRAMMAR=0`. The full Pydantic JSON-schema grammar is available behind
+  `LLAMA_CPP_USE_GRAMMAR=1`, but it hangs on Space CPU, so the Space uses strict
+  prompt-only JSON plus Pydantic validation. This replaces the slow CPU Transformers
+  runtime. The Transformers backend remains only as an explicit local experiment/fallback
+  path and is not installed by the default requirements.
 - **MVP training template:** use the supplied fixed 4-day exercise template for the
   first engine slice. Preserve exercise grouping, execution order, set counts, rep
   targets, and notes. For MVP simplicity, all exercise rests are normalized to 1 minute.

README.md

@@ -126,13 +126,16 @@ PARSER_BACKEND=llama_cpp
 LLAMA_CPP_MODEL_REPO=unsloth/Qwen3-1.7B-GGUF
 LLAMA_CPP_MODEL_FILE=Qwen3-1.7B-Q4_K_M.gguf
 LLAMA_CPP_MAX_TOKENS=384
-LLAMA_CPP_N_CTX=2048
+LLAMA_CPP_N_CTX=4096
 LLAMA_CPP_N_THREADS=2
+LLAMA_CPP_USE_GRAMMAR=0
 ```
 
 The Space README frontmatter preloads only the selected GGUF file at build time so the
 app does not need to download model weights during the first parser request. Set
-`LLAMA_CPP_N_THREADS` to the Space CPU thread count.
+`LLAMA_CPP_N_THREADS` to the Space CPU thread count. `LLAMA_CPP_USE_GRAMMAR=0` keeps
+llama.cpp on prompt-only JSON generation because the full Pydantic JSON-schema grammar
+was too slow on Space CPU. Pydantic validation still rejects malformed parser output.
 
 If `PARSER_BACKEND` is not set, the app chooses `llama_cpp` when the Hugging Face
 `SPACE_ID` environment variable exists, otherwise `ollama`.

tests/test_parser_llama_cpp.py

@@ -7,6 +7,7 @@ from training_coach.parser_llama_cpp import (
     DEFAULT_LLAMA_CPP_MODEL_FILE,
     DEFAULT_LLAMA_CPP_MODEL_REPO,
     DEFAULT_LLAMA_CPP_N_CTX,
+    DEFAULT_LLAMA_CPP_USE_GRAMMAR,
     LlamaCppRuntimeUnavailableError,
     _load_llama_cpp,
     generate_parser_response_llama_cpp,
@@ -70,7 +71,8 @@ class LlamaCppParserTest(unittest.TestCase):
         self.assertEqual(DEFAULT_LLAMA_CPP_MODEL_REPO, "unsloth/Qwen3-1.7B-GGUF")
         self.assertEqual(DEFAULT_LLAMA_CPP_MODEL_FILE, "Qwen3-1.7B-Q4_K_M.gguf")
         self.assertEqual(DEFAULT_LLAMA_CPP_MAX_TOKENS, 384)
-        self.assertEqual(DEFAULT_LLAMA_CPP_N_CTX, 2048)
+        self.assertEqual(DEFAULT_LLAMA_CPP_N_CTX, 4096)
+        self.assertEqual(DEFAULT_LLAMA_CPP_USE_GRAMMAR, False)
 
     def test_runtime_can_import_llama_cpp_or_reports_clear_error(self):
         try:
@@ -105,7 +107,7 @@ class LlamaCppParserTest(unittest.TestCase):
             ],
         )
 
-    def test_generate_parser_response_uses_schema_grammar(self):
+    def test_generate_parser_response_does_not_use_schema_grammar_by_default(self):
         with patch(
             "training_coach.parser_llama_cpp._load_llama_cpp",
             return_value=(FakeLlama, FakeGrammar),
@@ -122,6 +124,27 @@ class LlamaCppParserTest(unittest.TestCase):
         completion_call = FakeLlama.completion_calls[0]
         self.assertEqual(completion_call["max_tokens"], 128)
         self.assertEqual(completion_call["temperature"], 0)
+        self.assertNotIn("grammar", completion_call)
+        self.assertEqual(FakeGrammar.schemas, [])
+        self.assertIn("60 min", completion_call["messages"][1]["content"])
+        self.assertIn("check_in", response)
+
+    def test_generate_parser_response_can_use_schema_grammar_when_enabled(self):
+        with patch(
+            "training_coach.parser_llama_cpp._load_llama_cpp",
+            return_value=(FakeLlama, FakeGrammar),
+        ):
+            response = generate_parser_response_llama_cpp(
+                "60 min",
+                repo_id="repo/model",
+                filename="model.gguf",
+                max_tokens=128,
+                n_ctx=2048,
+                n_threads=None,
+                use_grammar=True,
+            )
+
+        completion_call = FakeLlama.completion_calls[0]
         self.assertEqual(completion_call["grammar"]["verbose"], False)
         self.assertEqual(FakeGrammar.schemas[0][1], False)
         self.assertIn("ParsedCheckIn", FakeGrammar.schemas[0][0])
@@ -137,6 +160,7 @@ class LlamaCppParserTest(unittest.TestCase):
                 "LLAMA_CPP_MAX_TOKENS": "128",
                 "LLAMA_CPP_N_CTX": "4096",
                 "LLAMA_CPP_N_THREADS": "2",
+                "LLAMA_CPP_USE_GRAMMAR": "1",
             },
             clear=True,
         ), patch(
@@ -150,6 +174,7 @@ class LlamaCppParserTest(unittest.TestCase):
         self.assertEqual(FakeLlama.from_pretrained_calls[0]["filename"], "model.gguf")
         self.assertEqual(FakeLlama.from_pretrained_calls[0]["n_ctx"], 4096)
         self.assertEqual(FakeLlama.from_pretrained_calls[0]["n_threads"], 2)
+        self.assertIn("grammar", FakeLlama.completion_calls[0])
 
 
 if __name__ == "__main__":

training_coach/parser_llama_cpp.py

@@ -17,7 +17,8 @@ from training_coach.parser import (
 DEFAULT_LLAMA_CPP_MODEL_REPO = "unsloth/Qwen3-1.7B-GGUF"
 DEFAULT_LLAMA_CPP_MODEL_FILE = "Qwen3-1.7B-Q4_K_M.gguf"
 DEFAULT_LLAMA_CPP_MAX_TOKENS = 384
-DEFAULT_LLAMA_CPP_N_CTX = 2048
+DEFAULT_LLAMA_CPP_N_CTX = 4096
+DEFAULT_LLAMA_CPP_USE_GRAMMAR = False
 logger = logging.getLogger(__name__)
 
 
@@ -43,6 +44,13 @@ def _optional_int_env(name: str) -> int | None:
     return int(raw_value)
 
 
+def _bool_env(name: str, default: bool) -> bool:
+    raw_value = os.getenv(name, "").strip().lower()
+    if not raw_value:
+        return default
+    return raw_value in {"1", "true", "yes", "on"}
+
+
 @lru_cache(maxsize=1)
 def load_llama_cpp_model(
     repo_id: str = DEFAULT_LLAMA_CPP_MODEL_REPO,
@@ -95,15 +103,18 @@ def generate_parser_response_llama_cpp(
     max_tokens: int = DEFAULT_LLAMA_CPP_MAX_TOKENS,
     n_ctx: int = DEFAULT_LLAMA_CPP_N_CTX,
     n_threads: int | None = None,
+    use_grammar: bool = DEFAULT_LLAMA_CPP_USE_GRAMMAR,
 ) -> str:
     start_time = perf_counter()
     messages = build_parser_messages(raw_text)
     logger.info(
-        "event=parser_llama_cpp_generate_start repo=%s file=%s text_chars=%s max_tokens=%s",
+        "event=parser_llama_cpp_generate_start repo=%s file=%s text_chars=%s "
+        "max_tokens=%s use_grammar=%s",
         repo_id,
         filename,
         len(raw_text),
         max_tokens,
+        use_grammar,
     )
     log_parser_messages(
         backend="llama_cpp",
@@ -116,12 +127,15 @@ def generate_parser_response_llama_cpp(
         n_ctx=n_ctx,
         n_threads=n_threads,
     )
-    response = model.create_chat_completion(
-        messages=messages,
-        max_tokens=max_tokens,
-        temperature=0,
-        grammar=llama_cpp_response_grammar(),
-    )
+    completion_kwargs = {
+        "messages": messages,
+        "max_tokens": max_tokens,
+        "temperature": 0,
+    }
+    if use_grammar:
+        completion_kwargs["grammar"] = llama_cpp_response_grammar()
+
+    response = model.create_chat_completion(**completion_kwargs)
     response_text = response["choices"][0]["message"]["content"].strip()
     logger.info(
         "event=parser_llama_cpp_generate_complete repo=%s file=%s "
@@ -145,6 +159,7 @@ def parse_check_in_with_llama_cpp(raw_text: str) -> ParsedCheckIn:
     max_tokens = int(os.getenv("LLAMA_CPP_MAX_TOKENS", str(DEFAULT_LLAMA_CPP_MAX_TOKENS)))
     n_ctx = int(os.getenv("LLAMA_CPP_N_CTX", str(DEFAULT_LLAMA_CPP_N_CTX)))
     n_threads = _optional_int_env("LLAMA_CPP_N_THREADS")
+    use_grammar = _bool_env("LLAMA_CPP_USE_GRAMMAR", DEFAULT_LLAMA_CPP_USE_GRAMMAR)
     response_text = generate_parser_response_llama_cpp(
         raw_text,
         repo_id=repo_id,
@@ -152,5 +167,6 @@ def parse_check_in_with_llama_cpp(raw_text: str) -> ParsedCheckIn:
         max_tokens=max_tokens,
         n_ctx=n_ctx,
         n_threads=n_threads,
+        use_grammar=use_grammar,
     )
     return parse_model_response(response_text)