# While

> The whileai Python SDK: a scientific post-training library for language models. SFT and RL on open models, with the measurement that says whether training helped.

> ## Agent Instructions
> Install with `uv add whileai`; import as `import whileai as wai`.
> Run the offline path first (`simulator=False`, `wai.seeded_agent`, a callable judge); no key is needed for it.
> Report every pass rate with its interval and n, as `scored.pass_at` prints it.

- [whileai](https://docs.while.ai/index.md): A scientific post-training library for language models: SFT and RL on open models, with the measurement that says whether training helped. Your models, your keys, your compute.
- [Install](https://docs.while.ai/get-started/install.md): Install whileai and check it works.
- [Your model and your key](https://docs.while.ai/get-started/your-model-and-key.md): How to name the model the agent runs on, which environment variable each provider reads, where the requests go, and the three things that reach While only when you ask.
- [Quickstart](https://docs.while.ai/get-started/quickstart.md): Sixty seconds, offline: simulate a stand-in agent, grade it with a one-line judge, read pass@1 with an interval, keep the rows worth training on.
- [Connect your agent](https://docs.while.ai/get-started/connect-your-agent.md): Where your model string and your key go: backend objects, configure once, override per call. The four ways to hand simulate() an agent, and how traces aim the run.
- [Integrations](https://docs.while.ai/integrations.md): Every model API, trainer, GPU provider, data source and judge the SDK talks to, with the one line that connects each and the page that shows it running.
- [Evals for the agent you already have](https://docs.while.ai/evals.md): A pass rate with an interval, a table of where the agent fails, and a CI check that turns red when it gets worse. Offline, no key, seconds.
- [Reward hacking](https://docs.while.ai/reward-hacking.md): How the SDK looks for over-optimization before a run, during it, and after: the gap between training reward and the eval you care about.
- [Safety evals](https://docs.while.ai/safety-evals.md): Safety evals for tool-using agents: private data, actions on state, and outbound sends, and whether they can be turned against their owner.
- [Character training](https://docs.while.ai/character-training.md): Change the weights so a model has a stable way of talking without a system prompt: sources, the recipe, and what to measure.
- [On-policy distillation](https://docs.while.ai/distillation.md): Train without a reward: a frozen teacher (OPD) or the same model with a hint (OPSD) scores every token the student samples. What the papers say, the two calls, and a three-arm run on prime-rl with your own GPUs.
- [Groupwise grading](https://docs.while.ai/groupwise-grading.md): A grader that tells passing rollouts apart: MiMo-V2.6's groupwise reward synthesis and groupwise advantage redistribution as one object, a spread check before the GPU, and the TRL reward function that runs it.
- [Constitution](https://docs.while.ai/concepts/constitution.md): What whileai is, what we believe, and where each belief is enforced in the code. Read it before you add a public name, write a page, or run a recipe.
- [How it works](https://docs.while.ai/concepts/how-it-works.md): How the simulator thinks and why: the four pieces of a rollout, the situations it covers, a world that says no, a judge that is measured, and the rows it returns.
- [The engine](https://docs.while.ai/concepts/engine.md): How simulate() makes evals and training data in eight steps: a pairwise covering array over situation axes, a novelty-weighted search, a sandbox world with failure modes, and a judge validated before training. With references.
- [FAQ](https://docs.while.ai/concepts/faq.md): What people ask before they start: what wai is, what you own at the end, whether you need a key, and how you know training helped. Every answer checked against the released package.
- [Recipes](https://docs.while.ai/recipes/index.md): One post-training run as five steps, each step a runnable, self-contained recipe: what you learn, what you need, how long it takes.
- [Bring your own agent](https://docs.while.ai/recipes/01-simulate/bring-your-own-agent.md): Three things a first run with your own agent needs: the callable contract, what the run says when the agent is broken, and how an eval score is kept out of the training reward.
- [Swarm rescue: passing rollouts on the tasks GRPO throws away](https://docs.while.ai/recipes/01-simulate/swarm-rescue.md): What you learn: on the tasks where the policy fails every one of 8 rollouts, whether a particle swarm of rollouts that share their best attempts finds a passing answer that resampling alone does not, at the same budget.
- [Verifiers: verifiable rewards](https://docs.while.ai/recipes/01-simulate/verifiers.md): A verifier is a reward that is a program, not an opinion, the reward of reinforcement learning with verifiable rewards [1].
- [Character to the wall](https://docs.while.ai/recipes/02-measure/character-to-the-wall.md): What you learn: whether a persona holds when two of its own values collide, not just whether it can state a trait in isolation.
- [Which judge can you trust?](https://docs.while.ai/recipes/02-measure/compare-judges.md): Six judges read the same 300 agent transcripts and answer one question each: did the agent do the job honestly?
- [Evals for the agent you already have](https://docs.while.ai/recipes/02-measure/eval-your-agent.md): Wrap the agent you ship, write its policy as a judge, roll every ask four times, and read pass@1 with an interval per policy branch.
- [Is your eval any good?](https://docs.while.ai/recipes/02-measure/is-your-eval-any-good.md): What you learn: whether a number your evaluation produced means anything, before you act on it.
- [pass@1, pass^k and pass@k for one agent](https://docs.while.ai/recipes/02-measure/pass-at-k.md): Three numbers off the same graded groups, one job each.
- [A public benchmark into the measurement](https://docs.while.ai/recipes/02-measure/public-benchmark.md): 200 GSM8K test questions and a model's answers become the rows every measurement reads, in one call, and every number comes out with its interval.
- [Reward hacking, caught three times](https://docs.while.ai/recipes/02-measure/reward-hacking.md): A reward is a proxy.
- [Safety evals for a tool-using agent](https://docs.while.ai/recipes/02-measure/safety-evals.md): An agent with tools can do three things a chatbot cannot: read private data, act on it, and send it somewhere.
- [Safety evals for a marketplace agent](https://docs.while.ai/recipes/02-measure/safety-evals-marketplace.md): The safety-evals example tests a support agent whose private data is one company's CRM.
- [Character training from a constitution](https://docs.while.ai/recipes/03-select/character.md): How a model talks when nobody told it how to talk.
- [Synthetic RL data for Prime Intellect](https://docs.while.ai/recipes/03-select/prime-intellect-rl.md): Generate a GRPO-ready dataset for a coding agent, then check it carries gradient before spending GPU time on it.
- [One row, six training targets](https://docs.while.ai/recipes/03-select/schema.md): Every row the SDK writes is a projection of four objects: Task (the situation), Rollout (one episode of one policy on it), Judgment (a scorer's verdict), and Marker (a behavior measurement).
- [DPO on Modal, with the dashboard watching](https://docs.while.ai/recipes/04-train/dpo.md): Direct preference optimization on the same environment as recipes/04-train/grpo: the refund assistant with one testable rule.
- [Train on Fireworks, serve on Fireworks, prove it through the same API](https://docs.while.ai/recipes/04-train/fireworks.md): While writes the dataset and measures the gain; Fireworks supplies the training GPUs and the endpoint. format="fireworks" on export and export_preference writes what a Fireworks managed training job reads, the firectl l.
- [GRPO on Modal, with the dashboard watching](https://docs.while.ai/recipes/04-train/grpo.md): Group-relative RL on one testable rule, end to end: prompts from the simulator, a reward that is a function rather than a judge, TRL's GRPOTrainer with a LoRA adapter, reward and KL on the training page as it runs, and.
- [The hosted loop: push, train, serve, call](https://docs.while.ai/recipes/04-train/hosted-loop.md): Four calls from graded rows to a chat completion from the trained model, all on the platform.
- [Identity dataset generator](https://docs.while.ai/recipes/04-train/identity.md): Builds a chat-format SFT set that teaches a model a new name and maker without letting the identity leak into normal behavior.
- [GRPO, OPSD and OPD on prime-rl, on Modal, with your keys](https://docs.while.ai/recipes/04-train/prime-rl.md): Three ways to a per-token training signal on one taskset, from one config writer, on two GPUs each: the taskset's reward (GRPO), the same model shown the answer (on-policy self-distillation, OPSD), and a frozen stronger.
- [Report a run so a person can decide](https://docs.while.ai/recipes/04-train/report-run.md): What you learn: the typed objects the platform tracks (a tracked agent with its harness, behaviors, runs, live traffic), why a harness is versioned by its fingerprint, and why a version is scored on every behavior.
- [Resist a planted instruction](https://docs.while.ai/recipes/04-train/resist-planted-instruction.md): Train an agent to ignore an instruction that arrives inside a tool result, and show that the reward filter, not the fine-tuning, is what taught it.
- [SFT on your own GPU, from the course's own export](https://docs.while.ai/recipes/04-train/sft.md): Lesson 7 of the course writes train.jsonl with select(mode="sft").export(...).
- [Text-to-SQL: hill-climb a model on your schema with a verifier as the reward](https://docs.while.ai/recipes/04-train/text-to-sql.md): A question about a database in, one SQL query out, and a reward that is a program: run the query, compare the result set to the gold query's result.
- [Serve a trained adapter on Amazon Bedrock](https://docs.while.ai/recipes/05-export/bedrock-import.md): Take a LoRA adapter you trained, merge it into its base, import the merged weights into your own AWS account with Bedrock Custom Model Import, and measure the served model on the same held-out tasks that scored it on vL.
- [Hugging Face, both directions](https://docs.while.ai/recipes/05-export/hugging-face.md): Push a graded dataset or a LoRA adapter to a Hub repo you own with your own token; through the platform, pull any Hub split onto your account and read its numbers before you train on it.
- [Papers](https://docs.while.ai/recipes/papers/index.md): One directory per paper.
- [Adaptive clip: the upper bound follows how rare a correct answer was](https://docs.while.ai/recipes/papers/adaptive-clip.md): Paper: Group Adaptive Clipping Policy Optimization, Sheng Jia et al., arXiv:2609.00444, August 2026.
- [BPCO bounded critic: a critic that can only say a number the reward could be](https://docs.while.ai/recipes/papers/bpco-bounded-critic.md): Paper: Best Practice Critic Optimization, Penghui Qi, Xiangxin Zhou, Wee Sun Lee (NUS / Tencent Hunyuan), arXiv:2608.23566, August 2026.
- [Endpoint SFT: keep the two ends of the reasoning trace, drop the middle](https://docs.while.ai/recipes/papers/endpoint-sft.md): Paper: Revisiting Complete Reasoning Traces for Post-Training, Jaehui Hwang et al., arXiv:2609.07103, September 2026.
- [Filter metric: phantom advantages under a shaped reward](https://docs.while.ai/recipes/papers/filter-metric.md): Paper: The Filter Metric is Safety-Critical: Phantom Advantages in Group-Relative RL under Shaped Rewards, Juntao Yu, arXiv:2609.13866, September 2026.
- [FlashREINFORCE: one stale rollout per prompt, corrected, gated, length-normalized](https://docs.while.ai/recipes/papers/flash-reinforce.md): Paper: FlashREINFORCE: Critic-Free Single-Rollout Asynchronous RL for Agentic Language Models, Yifan Hu et al., NVIDIA, September 2026 (no arXiv id yet).
- [GMTS: rank tokens by entropy times advantage, not by entropy alone](https://docs.while.ai/recipes/papers/gmts-token-select.md): Paper: GMTS: Gradient Magnitude-based Token Selection Improves RLVR Training, Outongyi Lv et al., arXiv:2608.30632, August 2026.
- [Harness and weights: both levers against either alone](https://docs.while.ai/recipes/papers/harness-and-weights.md): Paper: Harness-Aware Self-Evolving: Co-Evolving Model Weights, Harness, and Task Solutions (HASE), Haochen Luo et al., arXiv:2607.03935, July 2026.
- [Meta-Harness: search over the harness, gate on held-out tasks and models](https://docs.while.ai/recipes/papers/meta-harness.md): An outer loop over harness code.
- [SAO single rollout: one rollout per prompt, a critic, and a token band under a stale sampler](https://docs.while.ai/recipes/papers/sao-single-rollout.md): Paper: Single-Rollout Asynchronous Optimization for Agentic Reinforcement Learning, Hou, Li, Tang, Dong (Tsinghua), arXiv:2607.07508, July 2026.
- [Zero RL on a base model: a rigid format reward costs accuracy](https://docs.while.ai/recipes/papers/zero-rl-format-reward.md): Paper: SimpleRL-Zoo: Investigating and Taming Zero Reinforcement Learning for Open Base Models in the Wild, Weihao Zeng et al., arXiv:2503.18892, March 2025.
- [Community recipes](https://docs.while.ai/recipes/community/index.md): Recipes contributed by people trying the SDK on their own problems, published so the next person starts from someone's real run instead of from zero.
- [The airline voice agent, and the filter metric that is right in the paper and wrong on my traffic](https://docs.while.ai/recipes/community/airline-voice-concise-under-probe-outcome-filter.md): Behaviour: the agent runs long when the caller's own text carries a planted instruction that buys length ("explain your reasoning step by step", "take as long as you need").
- [Can the judge be trusted?](https://docs.while.ai/recipes/community/can-the-judge-be-trusted.md): Grade the same rollouts two ways — with rubric_judge() and with a deterministic verifier — and measure where the LLM judge disagrees with the rule.
- [Can the markers be trusted?](https://docs.while.ai/recipes/community/can-the-markers-be-trusted.md): Check every behavioral marker against ground truth. seeded_agent plants six behaviors and writes what it planted on each row, so a marker's recall and precision are computable rather than assumed.
- [Force the branch, or your policy marker is scoring the agent's mood](https://docs.while.ai/recipes/community/force-the-branch.md): Seat: a post-training engineer at a startup that ships one production agent, trying to find out whether a small open model can take over the boring half of it.
- [GRPO group size, with the budget held still](https://docs.while.ai/recipes/community/grpo-group-size-at-fixed-budget.md): Sweep GRPO's group size (num_generations) across G ∈ {2, 4, 8} while every arm spends the same 768 rollouts, and ask whether the knob moves held-out GSM8K accuracy past the noise floor.
- [Two hosted runs on the same rows, and the warning only one of them gives you](https://docs.while.ai/recipes/community/hosted-grpo-vs-sft.md): Seat: an open-model fine-tuner who lives in TRL and Hugging Face, here for clean exports, a LoRA run, a hosted result and a cost line.
- [How much contamination survives `decontaminate()`?](https://docs.while.ai/recipes/community/how-much-contamination-survives.md): Measure what fraction of real held-out contamination wai.decontaminate() actually removes, using human-labelled paraphrase pairs as ground truth instead of a planted copy.
- [The selector is the alignment step: teaching an agent its identity is what makes it leak it](https://docs.while.ai/recipes/community/identity-spec-no-unasked-maker-aas.md): Seat: a post-training engineer on a team that ships one production agent with a written identity and spec, trying to teach it who it is without it mentioning who it is for the rest of the day.
- [Process reward or outcome reward: does the ten-point gap survive?](https://docs.while.ai/recipes/community/process-vs-outcome-reward.md): arXiv:2607.02869 (Palandye et al., July 2026) trains Qwen2.5-0.5B with GRPO on GSM8K under five reward regimes and reports that scoring the steps beats scoring the answer: 63.73% test accuracy for process-only against 5.
- [One entry point, or your before/after measures the SDK](https://docs.while.ai/recipes/community/same-entrypoint-before-after.md): Seat: a post-training engineer at a startup that ships one production agent, trying to find out whether a small open model can take over the boring half of it.
- [The step the course skips](https://docs.while.ai/recipes/community/the-step-the-course-skips.md): The eight-lesson course for people who have never trained a model stops one line short of the training: # 2.
- [What TRL does with the loss mask](https://docs.while.ai/recipes/community/what-trl-does-with-the-loss-mask.md): wai.export(..., format="trl") writes a loss_mask on every row and reports mask_mode: "assistant".
- [Which half of my agent's traffic can a 1.5B model take over?](https://docs.while.ai/recipes/community/which-half-can-a-small-model-take.md): I have one production agent and a cost line to defend.
- [Who protects the held-out set: the ids, or the text?](https://docs.while.ai/recipes/community/who-protects-the-holdout.md): decontaminate() applies four rules in order.
- [Constitution](https://docs.while.ai/reference/constitution.md): What whileai is, what we believe, and where each belief is enforced in the code. Repeatable science, replicated papers as proof, your keys, ergonomics as the product.
- [Reference overview](https://docs.while.ai/reference/overview.md): What the whileai package is, how simulate() builds a row, and the three ways to run it: offline, on your own model, or on While-hosted models.
- [The five calls](https://docs.while.ai/reference/five-calls.md): Agent to gated dataset in five calls: simulate, grade, trust the judge, optimize, push. Plus the judge contract, verifiers, and the RL environment export.
- [Rows: the contract every measurement reads](https://docs.while.ai/reference/rows.md): The five row keys pass_at, compare, eval_variance, holdout_size, decontaminate and select read, which are required, and wai.rows(), the one call that builds them from a public benchmark.
- [The harness](https://docs.while.ai/reference/harness.md): The program around the model as one object: run it like an agent, version it like weights, and say which lever moved the score, the harness or the model.
- [The methods, in symbols](https://docs.while.ai/reference/methods.md): Every training method the library names, as one block of arithmetic each: the hosted four (SFT, GRPO, DPO, RM), the distillation pair (OPD, OPSD), the staleness corrections (Async), the group baselines prime-rl runs, and the three single-rollout updates, with a table from each symbol to the field th…
- [Style: how the language reads](https://docs.while.ai/reference/style.md): The coding standard for every public name: PyTorch and DSPy ergonomics, one import, objects carry configuration, calls carry data, reports print themselves.
- [Design: how the docs look](https://docs.while.ai/reference/design.md): The page templates, type, color and number rules that make docs.withwhile.com read as a scientific library, with the docs.json keys that carry them.
- [What to run](https://docs.while.ai/reference/what-to-run.md): Which mode fits the use case, how recommend() sizes a run from the agent's own grid, how mode="rl" spends rollouts, and how traces aim the budget.
- [Parameters and output](https://docs.while.ai/reference/parameters.md): Every simulate() parameter and advanced knob with its default, and what each row of the output carries.
- [Package layout and development](https://docs.while.ai/reference/development.md): Where the code lives, how to run the tests, lint and type checks, and what CI runs.
- [Learn post-training from zero](https://docs.while.ai/learn/index.md): Nine short lessons for an engineer who has never trained a model. Each one runs offline, with no key, in under a minute.
- [A model learns from examples, not from instructions](https://docs.while.ai/learn/what-training-does.md): Lesson 1. What a prompt cannot change and training can. Pretraining, post-training, SFT and RL, in plain words.
- [One saved conversation is a rollout](https://docs.while.ai/learn/what-a-rollout-is.md): Lesson 2. The row a model trains on: the ask, the tool calls, the reply. Where rows come from when you have no traffic yet.
- [A reward is a score you can defend](https://docs.while.ai/learn/what-a-reward-is.md): Lesson 3. A number per row, from a program that checks the answer or a model that reads it. How to check the checker before you trust it.
- [A pass rate without an interval is a guess](https://docs.while.ai/learn/why-one-number-is-not-a-result.md): Lesson 4. pass@1, the interval around it, pass^k and headroom, and how many tasks a real result needs.
- [The test the model never sees is the only score that counts](https://docs.while.ai/learn/the-held-out-set.md): Lesson 5. Split the rows before training, lock the test, and check that no training row is a copy of a test row. What the copy check catches and what it cannot see.
- [Train on what the model gets right sometimes](https://docs.while.ai/learn/which-rows-to-train-on.md): Lesson 6. Keep the passes for SFT. Keep the middle for RL, because a task the model always passes or always fails teaches nothing. Read the warnings.
- [Training is done when the held-out score moved](https://docs.while.ai/learn/train-and-prove.md): Lesson 7. Export the rows, train a LoRA adapter on one A10G on your own Modal account, and prove the change with a paired before and after on the held-out set.
- [A teacher can score every word](https://docs.while.ai/learn/learn-without-a-reward.md): Lesson 8. Training with no reward at all: a stronger model, or the same model shown the answer, scores each word the student wrote. When that beats a reward, when it cannot, and the two calls.
- [A production trace is one try with a score](https://docs.while.ai/learn/train-on-production-traces.md): Lesson 9. Real traffic comes one attempt per ask, scored after the fact, in a world you cannot replay. The three methods that train on exactly that shape, what they bring instead of a group, and what is proven so far.
- [Library and platform](https://docs.while.ai/platform/index.md): The library runs on your machine with no account. The platform adds hosted models, storage, training, serving and tracking behind one key. Where the line is.
- [Name things after your work](https://docs.while.ai/platform/naming.md): The platform shows the names your code sends. A coding agent names the agent, behaviors, versions and experiments in the team's own words, and the test by its content.
- [Say why it moved](https://docs.while.ai/platform/experiments.md): Before a coding agent posts a second version, a sweep or a training run, it follows the manage-experiments skill: the question first, then per run five lines (Changed, Moved, Why, Learned, Reproduce), one chart, the rows that failed, and readback(tracked) to read the page the way the person will.
- [Command line](https://docs.while.ai/get-started/cli.md): The wai command: sign in, check which key is in use, write an eval harness into a project, and read or promote what the platform tracks.
- [Platform: sign in, datasets, training, serving](https://docs.while.ai/reference/platform.md): Sign in, push and gate datasets, prune and check them, train on the platform or report your own run, and serve the result.
- [API reference](https://docs.while.ai/api/index.md): Every public name in whileai and whileai.simulations, with its signature and docstring, generated from the package.
- [whileai](https://docs.while.ai/api/whileai.md): The platform client: sign in, tracked agents, runs, verdicts.
- [whileai.simulations.data](https://docs.while.ai/api/data.md): SimulationData: the object simulate() returns, and what it can do next.
- [whileai.simulations.score](https://docs.while.ai/api/score.md): Grading, judge checks, pass@k, selection for SFT and RL, hack scans.
- [whileai.simulations.generate](https://docs.while.ai/api/generate.md): Situation writers, coverage axes, agent adapters, model backends.
- [whileai.simulations.world](https://docs.while.ai/api/world.md): The mock world that answers tool calls and fails on schedule.
- [whileai.simulations.verify](https://docs.while.ai/api/verify.md): Verifiable rewards: programmatic checks a judge cannot game.
- [whileai.simulations.constants](https://docs.while.ai/api/constants.md): Module-level constants and their defaults.
- [whileai.simulations.environment](https://docs.while.ai/api/environment.md): A verifiers environment for on-policy trainers.
- [whileai.simulations.export](https://docs.while.ai/api/export.md): JSONL, preference pairs, and RL environments out of graded rows.
- [whileai.simulations.ingest](https://docs.while.ai/api/ingest.md): Local trace loading, OTLP rows, and the dataset calls.
- [whileai.simulations.monitor](https://docs.while.ai/api/monitor.md): Watch a live training run for reward hacking.
- [whileai.simulations.run](https://docs.while.ai/api/run.md): The search loop that spends the budget.
- [whileai.simulations.schema](https://docs.while.ai/api/schema.md): The typed row schema and its conversions.
- [whileai.simulations.simulation](https://docs.while.ai/api/simulation.md): simulate(): the entry point, and every argument it takes.
- [whileai.simulations.training](https://docs.while.ai/api/training.md): Training runs, trainer callbacks, TRL export.