Update docs

Author: matanbt

README.md

@@ -96,15 +96,15 @@ result = optimizer.optimize_trigger(
 ```
 
 You can replace any component in this recipe code with another compatible one; e.g., swap the loss or optimizer with a more sophisticated one to enhance the jailbreak. 
-For more examples see [quickstart.ipynb](quickstart.ipynb) notebook, and the detailed guide on [adding a recipe](docs/guides/adding_a_recipe.md).
+For more examples see [quickstart.ipynb](quickstart.ipynb) notebook, and the detailed guide on [adding a recipe](https://tropt.dev/guides/adding_a_recipe.html).
 
 ### Build New Optimizers & Losses 🔬
 
 TROPT is designed as a **factory for new optimizers and losses**. Each is a self-contained module behind a compact, standardized interface. This makes optimizer and loss modules more transparent and easy to read, and easily extensible: creating a new optimizer largely amounts to defining its search algorithm, and a new loss to defining its core computation.
 TROPT internally handles the repeated logic required to operate these modules, including input--trigger management, batching, tokenization blocking, trigger gradient computation, etc.
 Your new optimizer or loss then composes automatically with every existing model and counterpart component.
 
-Quick examples for a custom optimizer and loss are in [quickstart.ipynb](quickstart.ipynb); the docs have more detailed guides on building [optimizers](docs/guides/adding_an_optimizer.md) and [losses](docs/guides/adding_a_loss.md).
+Quick examples for a custom optimizer and loss are in [quickstart.ipynb](quickstart.ipynb); the docs have more detailed guides on building [optimizers](https://tropt.dev/guides/adding_an_optimizer.html) and [losses](https://tropt.dev/guides/adding_a_loss.html).
 
 
 ## 🤖 Use TROPT with Your Coding Agent

docs/_static/custom.css

@@ -31,6 +31,15 @@ html[data-theme="dark"] {
 /* ==========================================================================
    Base API-page tweaks (kept from previous custom.css)
    ========================================================================== */
+/* Sphinx's basic.css bolds any inline code that's a cross-reference link
+   (`code.xref, a code { font-weight: bold }`). With autodoc xrefs all over the
+   guides this made most inline code look bold by default — match the weight
+   of plain (unlinked) inline literals instead. */
+code.xref,
+a code {
+  font-weight: inherit;
+}
+
 dl.class {
   margin: 20px 0;
   border: 0;

docs/guides/adding_a_model.md

@@ -418,14 +418,5 @@ class MyHFLMModel(
     def invoke_from_texts(self, input_texts, **kwargs): ...
 ```
 
-You do **not** implement `compute_loss_from_tokens`, `compute_grad_from_tokens`, or `compute_grad_from_embeds` — those come from `HuggingFaceBackendModel`.
+You do **not** need to implement `compute_loss_from_tokens`, `compute_grad_from_tokens`, or `compute_grad_from_embeds` — those come from `HuggingFaceBackendModel`.
 
----
-
-## Checklist
-
-1. **Verify optimizer compatibility** — Instantiate an optimizer that requires your model's mixins and confirm `model_requirements` validation passes.
-2. **Usage stats** — Confirm `invoke_from_tokens` calls `_update_invoke_stats` with `n_tokens`, `n_samples`, and `count_backward`. Gradient methods should pass `count_backward=True` to `invoke_from_tokens`. For HuggingFace models this is already handled by `HuggingFaceBackendModel`. This takes care of usage tracking and FLOPs.
-3. **Test** — Write tests covering initialization, the inference method, and each mixin method. Test both single and multi-template cases. See `tests/models/` for examples.
-
-> Want to contribute your model backend back to the TROPT package? See [CONTRIBUTING.md](https://github.com/matanbt/TROPT/blob/main/CONTRIBUTING.md) for the file placement, export, and testing steps.

tropt/optimizer/gcgplus_optimizer.py

@@ -70,6 +70,7 @@ def __init__(
         sample_n_replace: Union[int, Tuple[int, int]] = (1, 1),
         candidate_oversample_factor: float = 1.1,
         momentum: float = 0.0,
+        skip_visited: bool = False,
         # Trigger buffer size:
         buffer_size: Optional[int] = None,
         n_grad_avg: int = 1,
@@ -97,6 +98,8 @@ def __init__(
                 m = mu*m + (1-mu)*grad for candidate ranking instead of raw gradient.
                 Defaults to 0.0 (no momentum).
                 Reference: https://arxiv.org/abs/2405.01229 .
+            skip_visited: If True, never re-select a previously accepted trigger
+                (PAL-style); avoids cycling/stalling. Defaults to False.
             buffer_size: If set, maintain a buffer of the best triggers seen (from QCG paper). Each step
                 starts from the best buffer entry and updates it with improved candidates.
                 Defaults to None (no buffer).
@@ -147,6 +150,7 @@ def __init__(
         self.use_retokenize = use_retokenize
         self.candidate_oversample_factor = candidate_oversample_factor
         self.momentum = momentum
+        self.skip_visited = skip_visited
         self.use_token_input_for_loss = use_token_input_for_loss
         self.buffer_size = buffer_size
         self.n_grad_avg = n_grad_avg
@@ -185,6 +189,7 @@ def optimize_trigger(
 
         best = RunningBest()
         momentum_buffer: Optional[Tensor] = None
+        visited: set[str] = set()
 
         # Buffer initialization
         buffer: Optional[TriggerBuffer] = None
@@ -202,6 +207,8 @@ def optimize_trigger(
         ).item()
         trigger_str = proxy_tokenizer.decode_trigger(trigger_ids)
         self.log(loss=current_loss, trigger_str=trigger_str)
+        if self.skip_visited:
+            visited.add(trigger_str)
 
         n_replace_start, n_replace_end = self.sample_n_replace
 
@@ -286,6 +293,14 @@ def optimize_trigger(
                 candidate_trigger_ids = retokenize_filtering(
                     candidate_trigger_ids, proxy_tokenizer
                 )
+            # Drop already-accepted triggers (PAL-style) before truncating
+            if self.skip_visited and len(candidate_trigger_ids) > 0:
+                cand_strs = proxy_tokenizer.decode_triggers(candidate_trigger_ids)
+                keep = torch.tensor(
+                    [s not in visited for s in cand_strs],
+                    device=candidate_trigger_ids.device,
+                )
+                candidate_trigger_ids = candidate_trigger_ids[keep]
             # Truncate to n_candidates (after oversample + filter)
             candidate_trigger_ids = candidate_trigger_ids[: self.n_candidates]
 
@@ -314,6 +329,8 @@ def optimize_trigger(
 
             best.update(loss=current_loss, trigger_ids=trigger_ids, trigger_str=trigger_str)
             self.log(loss=current_loss, trigger_str=trigger_str)
+            if self.skip_visited:
+                visited.add(trigger_str)
 
         # --- Finalize ---
         result = best.to_result()