# ZeroProof Simulations SDK

Generate diverse, graded training data for any tool-using agent from its
spec alone. `zps.simulate` writes the user side of the conversation, rolls
the agent against a simulated tool backend, grades every trajectory, and
exports JSONL training rows.

Repo: https://github.com/Zero-Proof-AI/zeroproof-simulations (Apache-2.0)

## Install

```bash
git clone https://github.com/Zero-Proof-AI/zeroproof-simulations.git
cd zeroproof-simulations
pip install -e .
export VLLM_API_KEY=...   # ZeroProof hosted credential; contact ZeroProof
```

## Quickstart

```python
import zeroproof_simulations as zps

data = zps.simulate(spec="specs/github")   # 60s, up to 1000 rows
data.save("rollout.jsonl")
```

`spec` is a folder or file holding `{tools, policy}` in OpenAI function
schema format. Any agent spec works; nothing is hardcoded per domain. You
can pass `tools=` and `policy=` directly, or `agent=` (a callable, an
`https://...` endpoint, or `vllm:` / `ollama:` / `openai:`).

## Modes

- `mode="explore"`: every row a brand-new situation. Eval sets, coverage.
- `mode="sft"`: three differently phrased openers per situation, one
  trajectory each. Paraphrase-robust SFT.
- `mode="rl"`: one opener, three independent rollouts. Contrastive
  rewards for preference / GRPO training.
- `mode="adaptive"` (default): an allocator splits compute between
  exploring new situations, rephrasing known ones, and re-rolling on
  observed behavior.

`time_budget` (seconds, default 60) and `budget` (rows, default 1000) cap
compute. Exact dataset shape: `situations=`, `requests_per_situation=`,
`rollouts_per_request=`.

## Output rows

Each JSONL row: `prompt`, `messages` (user / assistant with `tool_calls` /
tool), `steps`, `final_text`, `scenario_id`, plus `reward` and `reason`
from the default deterministic conduct grader. Failures are labeled, not
dropped: fabricated references, success claims after tool faults, verbatim
repeats, truncations. An optional LLM judge
(`data.grade(llm=True, api_key=...)`) adds `llm_reward` / `llm_reason`.

## Measured

Two-minute runs on hosted Qwen, one A10G pool for writer and agent:
explore 317 rows, sft 379, rl 808 with 89 contrastive openers
(`specs/github`). Rollouts per request scale nearly linearly: k=8 wrote
975 rows in two minutes. A 20-tool spec wrote 394 sft rows in two minutes.

## Example data

`examples/` in the repo holds 600 real rows: explore, sft, and rl folders,
two agents each (lawfirm, gmail, coding, instagram, github, amazon), 100
rows per file, contrastive pairs first in the rl files.