whileai.simulations.generate

Situation writers, coverage axes, agent adapters, model backends. 18 public names. import whileai.simulations as wai, then wai.name.

Name	What it does
`AgentProfile`
`ModelSimulator`	Invent what a person might send, ask, or discuss; it never grades.
`World`	The mock world for a callable agent, faults first.
`adaptive_allocator`	Adaptive mix.
`allocator_slot_counts`	Integer explore/expand/verify slots from mix shares.
`build_dimensions`	Coverage axes from this agent.
`claude_code`
`connect`
`hosted_model`	The default simulation brain: hosted Qwen wearing these tools.
`inspect`	Read tools and system prompt off the agent; caller extras are merged in.
`local_model`	An agent that talks to an OpenAI-compatible endpoint (a served adapter, a local vLLM, any chat server) for `simulate(agent=...)`.
`novelty`	Min cosine distance from a candidate embedding to every tested row.
`open_ended_probes`	Taxonomy-free probes.
`policy_sections`	Split policy text into short rule clauses used as coverage cells.
`scenario_regions`	Weighted target regions over a pairwise covering set of the dimensions.
`seeded_agent`	A demo agent whose mistakes are on purpose and on the row.
`world`	A `World` for a callable agent: `world.call(tool, arguments)`.
`write_scene_brief`	One cheap LLM pass per simulate().

adapters

Framework adapters. Every runner returns {steps, final_text}.

AgentProfile

AgentProfile(
    tools: list[dict] = <factory>,
    policy: str = '',
    capabilities: dict = <factory>,
    constraints: dict = <factory>,
    transport: str = 'callable',
    name: str = '',
    rubric: str = '',
) -> None

claude_code

claude_code(
    extra_args: tuple | list = (),
    cwd: str | None = None,
    max_turns: int | None = None,
    timeout: float = 300.0,
) -> Callable

connect

connect(
    agent: Any,
    tools: list[dict] | None = None,
    system_prompt: str | None = None,
    policy: str | None = None,
    transport: str | None = None,
    execute: Callable | None = None,
    model: str | None = None,
) -> ConnectedAgent

inspect

inspect(
    agent: Any,
    tools: list[dict] | None = None,
    system_prompt: str | None = None,
    policy: str | None = None,
    transport: str | None = None,
) -> AgentProfile

Read tools and system prompt off the agent; caller extras are merged in.

agents

OpenAI-compatible chat loop for hosted and local simulation backends.

hosted_model

hosted_model(
    tools: list[dict],
    system: str = '',
    fault_plans: dict | None = None,
    **kwargs,
) -> Callable

The default simulation brain: hosted Qwen wearing these tools.

local_model

local_model(
    base_url: str,
    model: str,
    tools: list[dict],
    system: str = '',
    api_key: str | None = None,
    max_turns: int | None = None,
    avg_turns: float = 12.0,
    min_user_turns: int = 1,
    turn_stats: dict | None = None,
    temperature: float = 0.8,
    logprobs: bool | str = False,
    fault_plans: dict | None = None,
    result_shapes: dict | None = None,
    opening_rate: float = 0.0,
    human_tools: set | None = None,
    execute: Callable | None = None,
    timeout: float = 300.0,
    max_tokens: int | None = None,
    user_model: str | None = None,
    thinking: bool | None = None,
    patience: Patience | None = 'normal',
    user_temperature: float | None = None,
    world_options: WorldOptions | Mapping[str, Any] | None = None,
) -> Callable

An agent that talks to an OpenAI-compatible endpoint (a served adapter, a local vLLM, any chat server) for simulate(agent=...). thinking is for reasoning bases such as Qwen3: False sends chat_template_kwargs={"enable_thinking": False} so the reply is the answer, not the reasoning, the way the hosted Qwen path already does; True asks for it; None (the default) sends nothing and leaves the server’s default. The same field goes to the simulated user when the agent’s own model plays it (the default) or user_model sits on the same endpoint, so the customer is asked not to reason either; a user_model on another endpoint keeps that server’s default. Either way <think> markup never reaches step["text"], final_text, or a user turn (step["user"] and the messages history): what the user model still emits as reasoning is stripped before it becomes speech, and a turn that was reasoning with no spoken line is retried, then dropped (#284). The run reports those under search["user_think"]: user_turns, stripped and unclosed as counts, stripped_share and unclosed_share as shares of the user turns, zeros when none. result_shapes pins what a tool returns: \{tool_name: example result dict\}. The sandbox fills the example on every call instead of inventing a record, so a policy branch that only exists for some tool results (a credit over $200 must be escalated) is reached on purpose rather than by luck. Field names and free text stay as written; ids, dates and people are re-drawn per call, and a number moves by up to about a third of itself (900.0 lands in roughly 600 to 1200, 90.0 in 60 to 120), so pick a template value whose whole range sits on the side of the threshold you want. An argument that shares a key with the template is echoed back (invoice_id in, same invoice_id out). To measure a branch, run the same pinned tasks under two shapes, one per side of the rule. Without it the situation writer drafts an example per tool (write_result_shapes) and the branch is exercised at random. fault_plans schedules faults per ask: \{message: \{tool_name: \{"mode": "timeout", "rate": 1.0\}\}\}, keyed by the exact user message, with mode one of timeout, malformed, stale or permission_denied and rate the chance the fault fires on a call. The plan may also carry world_state, stance, tone and texture, which are popped off and shape the world and the simulated user for that ask. simulate() writes these itself from fault_rate=; pass your own only to replay a known plan (tasks= does this for you). timeout is seconds per completion, LOCAL_MODEL_TIMEOUT (300) by default: a served model that scaled to zero takes two to three minutes to answer its first request, and a timeout under that drops every rollout of the first pass. When a call still times out the run says so in data.warnings with the fix (raise timeout=, or send one throwaway request first so the endpoint is warm). patience is a level name (PATIENCE_LEVELS) or a table {"second": p, "later": q}: the chance the person leaves at the agent’s second question and at every later one, fitted from your own traces (see PATIENCE_HAZARDS). user_temperature is the sampling temperature of every simulated-user line, follow-ups (USER_TURN_TEMPERATURE) and human-tool answers (HUMAN_TOOL_TEMPERATURE) alike; None keeps those two defaults. world_options is the mock world’s dials (a WorldOptions or the same fields as a dict: fault modes, hit counts, name pools, …); simulate(advanced={"world": {...}}) lands here. None is the defaults in defaults.py.

diversity

Sparse generic writer knobs and annealing helpers.

adaptive_allocator

adaptive_allocator(
    time_budget: float | None,
    until: str = 'compute',
    elapsed: float | None = None,
) -> dict[str, Any]

Adaptive mix. Short remaining clock is messier; saturation walks more cards. Shares are explore / expand / verify. n_req and k are caps so expand and verify can actually run. Not a pinned n=1 k=1 policy.

allocator_slot_counts

allocator_slot_counts(take: int, plan: dict | None) -> dict[str, int]

Integer explore/expand/verify slots from mix shares.

generator

Model-driven scenario generation. Templates are bootstrap and offline fallback.

ModelSimulator

ModelSimulator(
    backend_spec: str | None = None,
    tools: Sequence[dict] = (),
    policy: str = '',
    candidates_per_round: int = 160,
    seed: int = 0,
    dimensions: dict | None = None,
    timeout: float = 30.0,
    cells_per_request: int | None = None,
    completions: int | None = None,
    distinct_cards: bool = False,
    extra_cards: int = 1,
    texture_rate: float | None = None,
    kind: str | None = None,
    scene_brief: str = '',
    out_tokens: int | None = None,
    time_budget: float | None = None,
    run_started: float | None = None,
    mode: str | None = None,
    prefer_success: bool | None = None,
    steering_weight: float | None = None,
    hard_share: float | None = None,
    writer_temperature: float | tuple[float, float] | None = None,
    world: Any = None,
)

Invent what a person might send, ask, or discuss; it never grades.

write_scene_brief

write_scene_brief(
    tools: Sequence[dict] = (),
    policy: str = '',
    backend_spec: str | None = None,
    kind: str = '',
    timeout: float = 8.0,
) -> str

One cheap LLM pass per simulate(). Private writer context. Empty on failure.

offline_agent

The free path, with something to catch.

World

World(tools: Sequence[dict] | None = None, seed: int = 0) -> None

The mock world for a callable agent, faults first. Built once; call reads the rollout being answered from current_rollout (thread-local, set by simulate before each rollout) so the row’s own faults and world_state apply. Outside a run it answers with no faults and no world state.

World.call

call(self, tool: str, arguments: dict | None = None) -> dict[str, Any]

The world’s answer to one tool call. Scheduled faults apply first.

seeded_agent

seeded_agent(
    tools: Sequence[dict],
    rate: float = 0.35,
    seed: int = 0,
    behaviors: Sequence[str] | None = None,
) -> Callable[[str], dict]

A demo agent whose mistakes are on purpose and on the row. Honest by default: it picks the tool the ask names, calls it through world() (faults fire), and reports what came back. On rate of rollouts, drawn deterministically from seed, the prompt and the rollout index, it does one thing from behaviors (default SEEDED_BEHAVIORS): hedging, sycophancy, apology and boilerplate add the phrase style_report looks for; ignore_fault claims success although the tool faulted; leak quotes the row’s privileged context. Each row it answers carries seeded: what it did on purpose, [] when it behaved.

world

world(tools: Sequence[dict] | None = None, seed: int = 0) -> World

A World for a callable agent: world.call(tool, arguments). Pass the same tools you pass simulate. Inside a run the row’s scheduled faults fire on it; a callable that answers its tool calls through this sees them, and the row’s faults stop being a label with no effect.

scenarios

Coverage cells from the agent’s tools and policy, plus offline fallback wording.

build_dimensions

build_dimensions(tools: list[dict], policy: str = '') -> dict[str, list[str]]

Coverage axes from this agent. Length and vagueness are writer-only.

novelty

novelty(candidate_vector, tested_matrix) -> float

Min cosine distance from a candidate embedding to every tested row.

open_ended_probes

open_ended_probes(
    tools: list[dict],
    policy: str = '',
    per_round: int = 10,
    seed: int = 0,
) -> list[str]

Taxonomy-free probes. Wording rotates with seed.

policy_sections

policy_sections(policy: str, cap: int = 16) -> list[str]

Split policy text into short rule clauses used as coverage cells. Identity / system-prompt preambles are not clauses. A long unsplit paragraph is dropped rather than truncated mid-word into rule.

scenario_regions

scenario_regions(
    tools: list[dict],
    policy: str = '',
    strength: int = 2,
    observed_counts: dict[str, int] | None = None,
    novelty: Callable[[dict], float] | None = None,
    behavior_value: Callable[[dict], float] | None = None,
    alpha: float = 0.35,
    beta: float = 0.35,
    gamma: float = 0.2,
    delta: float = 0.1,
    dimensions: dict | None = None,
    mode: str | None = None,
    prefer_success: bool | None = None,
) -> list[dict]

Weighted target regions over a pairwise covering set of the dimensions. prefer_success defaults off in mode="rl" so fault cells survive for covering-grid RL data. Explicit True/False always wins.

Get started

Guides

Concepts

Reference

API

whileai.simulations.generate

adapters

AgentProfile

claude_code

connect

inspect

agents

hosted_model

local_model

diversity

adaptive_allocator

allocator_slot_counts

generator

ModelSimulator

write_scene_brief

offline_agent

World

World.call

seeded_agent

world

scenarios

build_dimensions

novelty

open_ended_probes

policy_sections

scenario_regions

​adapters

​AgentProfile

​claude_code

​connect

​inspect

​agents

​hosted_model

​local_model

​diversity

​adaptive_allocator

​allocator_slot_counts

​generator

​ModelSimulator

​write_scene_brief

​offline_agent

​World

​World.call

​seeded_agent

​world

​scenarios

​build_dimensions

​novelty

​open_ended_probes

​policy_sections

​scenario_regions

adapters

AgentProfile

claude_code

connect

inspect

agents

hosted_model

local_model

diversity

adaptive_allocator

allocator_slot_counts

generator

ModelSimulator

write_scene_brief

offline_agent

World

World.call

seeded_agent

world

scenarios

build_dimensions

novelty

open_ended_probes

policy_sections

scenario_regions