feat(internals): add verbose logging to ReasoningBudgetSampler

- Add `verbose` parameter to ReasoningBudgetSampler to print high-level
  state transitions to stderr.
- Log key events: initialization, reasoning_start matched, budget exhausted,
  forced end sequence, UTF-8 boundary waiting, manual force, natural end, reset.
- Pass `verbose=getattr(model, "verbose", False)` from LlamaSamplingContext
  when building the sampler chain.
- Preserve verbose flag when cloning the sampler.

Signed-off-by: JamePeng <jame_peng@sina.com>

Author: JamePeng

llama_cpp/_internals.py

@@ -3,6 +3,7 @@
 import ctypes
 import enum
 import os
+import sys
 
 from typing import (
     Callable,
@@ -1566,6 +1567,9 @@ def __init__(
             sorted=False,
         )
 
+        # Active Python reasoning-budget sampler for this sampling context.
+        self.reasoning_budget_sampler: Optional[ReasoningBudgetSampler] = None
+
         # Sampler chain
         if _existing_sampler:
             self.sampler_chain = _existing_sampler
@@ -1583,9 +1587,6 @@ def __init__(
                 params.grammar_triggers,
             )
 
-        # Active Python reasoning-budget sampler for this sampling context.
-        self.reasoning_budget_sampler: Optional[ReasoningBudgetSampler] = None
-
     def _build_sampler_chain(self):
         """
         Build sampler chain aligned with llama.cpp common_sampler_init
@@ -1682,6 +1683,7 @@ def _build_sampler_chain(self):
                 ),
                 start_max_tokens=p.reasoning_start_max_tokens,
                 wait_utf8=True,
+                verbose=getattr(m, "verbose", False),
             )
 
             # Keep a direct Python reference so force_reasoning_budget() can
@@ -2131,6 +2133,7 @@ def __init__(
         initial_state: ReasoningBudgetState = ReasoningBudgetState.IDLE,
         start_max_tokens: Optional[int] = 32,
         wait_utf8: bool = True,
+        verbose: bool = False,
     ):
         """
         Initialize the reasoning budget sampler.
@@ -2182,6 +2185,11 @@ def __init__(
                 If True, when the budget is exhausted on an incomplete UTF-8
                 token piece, wait until a complete UTF-8 boundary before forcing
                 the end sequence.
+
+            verbose:
+                If True, print high-level reasoning-budget state transitions to
+                stderr. Logging is intentionally limited to transitions instead
+                of per-token events to avoid noisy generation output.
         """
         if model is None:
             raise ValueError("model must not be None")
@@ -2242,6 +2250,10 @@ def __init__(
         # Whether to delay forcing until a complete UTF-8 boundary.
         self.wait_utf8 = wait_utf8
 
+        # Whether to print high-level state transition logs.
+        # This follows the model/runtime verbose flag and avoids per-token spam.
+        self.verbose = verbose
+
         # Keep cloned Python sampler objects alive when llama.cpp clones the
         # sampler chain. Without this, cloned Python callbacks could be garbage
         # collected while C still holds function pointers to them.
@@ -2258,6 +2270,19 @@ def __init__(
             name="reasoning-budget",
         )
 
+        if self.verbose:
+            print(
+                f"ReasoningBudgetSampler: initialized "
+                f"(state={self.state.name}, budget={self.reasoning_budget}, "
+                f"start_max_tokens={self.start_max_tokens}, wait_utf8={self.wait_utf8}).",
+                file=sys.stderr,
+            )
+
+    def _log(self, message: str) -> None:
+        """Print a verbose reasoning-budget state transition message."""
+        if self.verbose:
+            print(f"ReasoningBudgetSampler: {message}", file=sys.stderr)
+
     def force(self) -> bool:
         """
         Manually transition the active reasoning block into forced ending.
@@ -2278,6 +2303,7 @@ def force(self) -> bool:
         self.state = ReasoningBudgetState.FORCING
         self.force_pos = 0
         self.end_matcher.reset()
+        self._log("manual force requested; entering FORCING state.")
         return True
 
     def _token_utf8_complete(self, token: int) -> bool:
@@ -2313,9 +2339,11 @@ def _start_counting(self) -> None:
         self.remaining = self.reasoning_budget
         self.end_matcher.reset()
         self.force_pos = 0
+        self._log(f"reasoning_start matched; entering COUNTING state (budget={self.reasoning_budget}).")
 
         if self.remaining <= 0:
             self.state = ReasoningBudgetState.FORCING
+            self._log("budget is 0; entering FORCING state immediately.")
 
     def _accept(self, token: int) -> None:
         """
@@ -2345,6 +2373,10 @@ def _accept(self, token: int) -> None:
                 and self.generated_tokens >= self.start_max_tokens
             ):
                 self.state = ReasoningBudgetState.DONE
+                self._log(
+                    f"reasoning_start not found within {self.start_max_tokens} generated tokens; "
+                    "switching to DONE passthrough."
+                )
             return
 
         if self.state in (
@@ -2353,6 +2385,7 @@ def _accept(self, token: int) -> None:
         ):
             if self.end_matcher.advance(token):
                 self.state = ReasoningBudgetState.DONE
+                self._log("reasoning_end matched naturally; switching to DONE passthrough.")
                 return
 
             utf8_complete = self._token_utf8_complete(token)
@@ -2362,6 +2395,7 @@ def _accept(self, token: int) -> None:
                     self.state = ReasoningBudgetState.FORCING
                     self.force_pos = 0
                     self.end_matcher.reset()
+                    self._log("UTF-8 boundary reached; entering FORCING state.")
                 return
 
             self.remaining -= 1
@@ -2370,15 +2404,18 @@ def _accept(self, token: int) -> None:
                     self.state = ReasoningBudgetState.FORCING
                     self.force_pos = 0
                     self.end_matcher.reset()
+                    self._log("reasoning budget exhausted; entering FORCING state.")
                 else:
                     self.state = ReasoningBudgetState.WAITING_UTF8
                     self.end_matcher.reset()
+                    self._log("reasoning budget exhausted; waiting for UTF-8 boundary before forcing.")
             return
 
         if self.state == ReasoningBudgetState.FORCING:
             self.force_pos += 1
             if self.force_pos >= len(self.forced_tokens):
                 self.state = ReasoningBudgetState.DONE
+                self._log("forced end sequence completed; switching to DONE passthrough.")
             return
 
         if self.state == ReasoningBudgetState.DONE:
@@ -2448,6 +2485,8 @@ def _reset(self) -> None:
         if self.state == ReasoningBudgetState.COUNTING and self.remaining <= 0:
             self.state = ReasoningBudgetState.FORCING
 
+        self._log(f"reset to {self.state.name} state.")
+
     def _clone(self):
         """
         Clone the full runtime state.
@@ -2464,6 +2503,7 @@ def _clone(self):
             initial_state=self.initial_state,
             start_max_tokens=self.start_max_tokens,
             wait_utf8=self.wait_utf8,
+            verbose=self.verbose,
         )
 
         cloned.remaining = self.remaining