# TROPT

> TROPT (Textual Trigger Optimization Toolbox) is a Python package for optimizing discrete text **triggers** that, when slotted into a user-supplied template, make a target NLP model produce a desired output. The same algorithm family powers LLM jailbreaks, corpus poisoning against dense retrievers, classifier evasion, prompt recovery from images, activation steering, and related research.

TROPT is built on **four foundational components**: **model** (the target NLP model the trigger is optimized against), **loss** (the quantifiable objective), **optimizer** (the search algorithm that minimizes the loss), and **inputs and targets** (the user-supplied input template(s) within which the trigger is optimized, with optional per-input targets). Instantiating and assembling the four yields an executable **recipe**. Two design principles keep this clean: *modularity* (each component swaps largely independently of the others) and *backend–frontend separation* (model-specific plumbing — tokenization, batching, gradient computation — is absorbed into the model "backend," keeping the loss and optimizer "frontend" lightweight). Models expose capabilities via **access mixins** (e.g. `LossTokenAccessMixin`, `GradientTokenAccessMixin`); optimizers declare their `model_requirements` at class level and the framework validates compatibility. The **Recipe Hub** ships 40+ pre-wired (model, loss, optimizer, inputs) combinations as one-call functions covering papers like GCG, BEAST, MAC, ARCA, PEZ, PRS, GASLITE, AutoPrompt, FLRT, GBDA, HotFlip, IRIS, PAL, QCG, SoftPrompt, UAT, and AdvDecoding.

This is defensive-security research tooling: use it for robustness evaluation, red-teaming with authorization, and academic research.

## Getting started

- [README](https://raw.githubusercontent.com/matanbt/TROPT/main/README.md): install (`pip install tropt` or `pip install tropt[all]`), 30-second jailbreak example, link map.
- [Quickstart notebook](https://raw.githubusercontent.com/matanbt/TROPT/main/quickstart.ipynb): end-to-end examples for jailbreaks, embedding attacks, custom objectives, black-box models.
- [PyPI page](https://pypi.org/project/tropt/): authoritative install info and version history.

## Usage guides

- [Running a recipe](https://tropt.dev/guides/running_a_recipe.md): the most common entry point — pick a recipe from `tropt.recipe_hub`, call it with `model_name` + `instruction` + `target_response`, get back an `OptimizerResult`.
- [Composing a recipe](https://tropt.dev/guides/adding_a_recipe.md): write your own recipe by wiring Model + Loss + Optimizer + Inputs. Covers trackers, token constraints, token initializers, `CombinedLoss`, paper-faithful defaults.
- [Adding a loss](https://tropt.dev/guides/adding_a_loss.md): the one rule — your `__call__` parameter names must match field names on `ModelOutput` / `ModelInput` / `MessageTargets`. The resolver auto-wires data into your loss.
- [Adding an optimizer](https://tropt.dev/guides/adding_an_optimizer.md): self-contained one-file optimizer with explicit `model_requirements = (Mixin1, Mixin2, ...)`. Backend handles tokenization, batching, gradients; you write only the search algorithm.
- [Adding a model](https://tropt.dev/guides/adding_a_model.md): implement the three method families (`invoke_from_*`, `set_inputs_from_*`/`reset_inputs_from_*`, `compute_{value}_from_{input_type}`) for whichever access mixins your backend can support.
- [Compatibility matrix](https://tropt.dev/guides/compatibility_matrix.md): auto-generated table of which (Model, Loss, Optimizer) triples actually work together.

## API reference

- [API index](https://tropt.dev/api/index.html): auto-generated reference for all public modules.
- [`tropt.common`](https://tropt.dev/api/common.html): `ModelInput`, `ModelOutput`, `Targets`, `MessageTargets`, `SliceKey`, `OPTIMIZED_TRIGGER_PLACEHOLDER`. Start here when reading loss / optimizer signatures.
- [`tropt.model`](https://tropt.dev/api/models.html): base classes, access mixins, and concrete backends (`LMHFModel`, `EncoderHFModel`, `EncoderOpenAIModel`, `LiteLLMModel`, `EncoderGeminiModel`, `EncoderVoyageModel`).
- [`tropt.loss`](https://tropt.dev/api/loss.html): base classes (`TriggerLogitBasedLoss`, `EmbeddingBasedLoss`, `TextBasedLoss`, `AttentionBasedLoss`, `HiddenStateBasedLoss`, `CombinedLoss`) and the resolver (`resolve_and_compute_loss`).
- [`tropt.optimizer`](https://tropt.dev/api/optimizer.html): `BaseOptimizer`, `OptimizerResult`, and every concrete optimizer (one per file).
- [`tropt.recipe_hub`](https://tropt.dev/api/recipe_hub.html): the full registry of one-call recipes and `list_recipes()`.

## Source code (single source of truth)

When in doubt, read installed source — the published docs may lag a release.

- [Repository root](https://github.com/matanbt/TROPT/tree/main): browse the source tree.
- [`tropt/recipe_hub/__init__.py`](https://raw.githubusercontent.com/matanbt/TROPT/main/tropt/recipe_hub/__init__.py): the canonical recipe registry (`RECIPES` dict). Read this to see every available recipe and the module it lives in.
- [`tropt/recipe_hub/README.md`](https://raw.githubusercontent.com/matanbt/TROPT/main/tropt/recipe_hub/README.md): table of recipes by task and access level, with paper citations.
- [`tropt/common.py`](https://raw.githubusercontent.com/matanbt/TROPT/main/tropt/common.py): all shared types — read this when working out a loss signature or a `Targets` payload.

For pip-installed users without a checkout: `python -c "import tropt, os; print(os.path.dirname(tropt.__file__))"` finds the on-disk source.

## Contributing

- [CONTRIBUTING.md](https://raw.githubusercontent.com/matanbt/TROPT/main/CONTRIBUTING.md): registration, naming convention (`{method}[_{variant}][_{task}][__{paperYYYY}]`), test conventions, and the compat-matrix regeneration step required for every PR.
- [TESTING.md](https://raw.githubusercontent.com/matanbt/TROPT/main/TESTING.md): per-component test checklists (new model / new loss / new optimizer).

## Optional

- [DESIGN.md](https://raw.githubusercontent.com/matanbt/TROPT/main/DESIGN.md): deep dive on architectural decisions — why mixins, why one-file optimizers, why parameter-name-matched losses. Read this when proposing architectural changes, not for routine usage.
- [GitHub Releases](https://github.com/matanbt/TROPT/releases): version history and breaking-change notes.