scaleapi-vero 0.5.0__tar.gz

scaleapi_vero-0.5.0/.gitignore

@@ -0,0 +1,40 @@
+# Environment
+.env
+.env.*
+.venv/
+venv/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+!src/vero/harbor/build/
+!src/vero/harbor/build/*.py
+!src/vero/harbor/build/templates/
+!src/vero/harbor/build/templates/*
+
+#harbor
+jobs/
+
+# Testing
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Jupyter
+**/.ipynb_checkpoints
+
+# OS
+.DS_Store
+Thumbs.db

scaleapi_vero-0.5.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: scaleapi-vero
+Version: 0.5.0
+Summary: A harness for agents to optimize programs.
+Author-email: Varun Ursekar <oss@scale.com>
+License: MIT
+Requires-Python: <3.14,>=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: wcmatch>=10.1
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk>=0.1.56; extra == 'claude'
+Provides-Extra: harbor
+Requires-Dist: fastapi>=0.110; extra == 'harbor'
+Requires-Dist: httpx>=0.28.1; extra == 'harbor'
+Requires-Dist: jinja2>=3.1.6; extra == 'harbor'
+Requires-Dist: pyyaml>=6.0.2; extra == 'harbor'
+Requires-Dist: uvicorn>=0.27; extra == 'harbor'
+Provides-Extra: interpret
+Requires-Dist: openai>=1.0; extra == 'interpret'
+Provides-Extra: optimize
+Requires-Dist: async-lru>=2.0.5; extra == 'optimize'
+Requires-Dist: beautifulsoup4>=4.14.2; extra == 'optimize'
+Requires-Dist: httpx>=0.28.1; extra == 'optimize'
+Requires-Dist: lxml>=6.0.2; extra == 'optimize'
+Requires-Dist: openai-agents[litellm]<0.19,>=0.18.3; extra == 'optimize'
+Requires-Dist: orjson>=3.10; extra == 'optimize'
+Requires-Dist: pypdf>=6.2.0; extra == 'optimize'
+Requires-Dist: trafilatura>=2.0.0; extra == 'optimize'
+Provides-Extra: wandb
+Requires-Dist: wandb>=0.19.10; extra == 'wandb'
+Description-Content-Type: text/markdown
+
+# VeRO: a harness for agents to optimize programs, text, and agents
+
+[![Paper](https://img.shields.io/badge/arXiv-2602.22480-b31b1b.svg)](https://arxiv.org/abs/2602.22480)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+
+VeRO gives an optimizer something to edit, a controlled way to evaluate it, and
+durable memory of everything it tried. The target is anything you can put under
+Git and score — a **program** (one function to a whole repo), **text** (a prompt,
+spec, or config), or an **agent** (its scaffold, tools, and prompts).
+
+VeRO runs the same **version → evaluate → select** loop over all of them. *Where*
+each candidate is produced and contained is a swappable backend, and **Harbor is
+the recommended one**: it runs the whole coding agent inside a reproducible,
+credential-isolated container and scores it against a trusted evaluation sidecar.
+That is the right default for optimizing agents and for any untrusted or
+reproducibility-critical run. Lighter local backends exist for trusted work that
+does not need containment.
+
+```
+  ┌─────────────────────────┐   submit candidate    ┌─────────────────────────┐
+  │  candidate production   ├──────────────────────►│  evaluation service     │
+  │                         │                       │                         │
+  │  coding agent, command, │◄──────────────────────┤  owns cases + scoring   │
+  │  or custom strategy;    │  score + diagnostics  │                         │
+  │  edits its own Git      │                       │  development: may ask   │
+  │  worktree per candidate │                       │  validation:  aggregate │
+  └───────────┬─────────────┘                       │  test:        withheld  │
+              │ commit                              └───────────┬─────────────┘
+              ▼                                                 │ report
+  ┌─────────────────────────┐    next round     ┌───────────────▼─────────────┐
+  │  candidate history:     │◄──────────────────┤  selection: keep the best   │
+  │  every version kept,    │                   │  feasible candidate         │
+  │  each one re-selectable │                   └─────────────────────────────┘
+  └─────────────────────────┘
+
+  Every model call on both sides goes through the inference gateway, which holds
+  the provider key and meters spend in tokens against a per-scope budget.
+```
+
+## Install
+
+```bash
+uv sync --extra optimize        # or --all-extras for the full toolchain
+uv run vero --help
+```
+
+> The published distribution is **`scaleapi-vero`** (`pip install scaleapi-vero`);
+> it imports as `vero`. Do **not** install `scale-vero` from PyPI — that name is
+> an unrelated placeholder squatted in July 2026, not VeRO.
+
+Python 3.11–3.13. 3.14 is excluded because litellm does not build there.
+
+## Quickstart — no credentials needed
+
+The C matrix-multiplication example is deterministic and runs with **no model
+credentials at all**. Its editable target contains only C; a trusted external
+harness compiles it, checks correctness, and measures latency.
+
+```bash
+cd examples/c-matmul/target
+git init -b main && git add .
+git -c user.name=vero -c user.email=vero@localhost commit -m baseline
+cd ..
+
+uv run vero evaluate --config vero.toml     # score the baseline
+uv run vero run --config vero.toml          # optimize
+```
+
+VeRO evaluates the baseline, gives an isolated worktree to the configured
+producer, evaluates its commit, selects the faster feasible result, and leaves
+the original target untouched.
+
+## Examples
+
+Each is a complete, checked-in target plus harness — clone-and-run, not a sketch.
+
+| Example | Optimizes | Needs |
+| --- | --- | --- |
+| [`c-matmul`](examples/c-matmul/) | a C matmul kernel, for latency under a correctness constraint | **nothing** — deterministic, no credentials |
+| [`circle-packing`](examples/circle-packing/) | a packing algorithm: 26 circles in a unit square, maximizing the sum of radii | a model, via `LITELLM_BASE_URL`/`LITELLM_API_KEY` or `OPENAI_BASE_URL`/`OPENAI_API_KEY` |
+| [`harbor-circle-packing`](examples/harbor-circle-packing/) | the same target, but with the agent contained and scored by a sidecar | Docker + credentials |
+| [`harness-conformance`](examples/harness-conformance/) | nothing — it checks the *stack*: whether a new agent or model can actually drive a run | credentials for the pair under test |
+
+Run `harness-conformance` before spending a real benchmark on a new harness or
+model. Every harness addresses its provider differently, and it costs minutes to
+find that out instead of hours.
+
+### A real run, end to end
+
+`harbor-circle-packing` runs a coding agent in a container, scores each candidate
+through a trusted sidecar, and finalizes on a `test` partition the agent never
+touches. One run with `mini-swe-agent` and `claude-sonnet-5`:
+
+![circle-packing search progress](examples/harbor-circle-packing/results/progress.svg)
+
+**0.9598 → 2.5766 on the held-out partition**, `shipped: true`, in about an hour.
+The best published result for 26 circles is ~2.635. The agent wrote a 15 KB
+Lubachevsky–Stillinger-style growth algorithm with LP refinement — no hardcoded
+coordinates.
+
+Two details worth reading off the left panel. The red point is an **infeasible**
+candidate: it scored 2.5341 but overlapped, the harness rejected it on the
+`valid == 1` constraint, and the agent's next commit was "Add safety margin to
+guarantee strict feasibility". And the last five evaluations are flat — it found
+the idea early, then polished.
+
+**The cautionary half.** The same task run with `codex` and no prohibition on
+hardcoding scored **2.6360 in eight minutes** — higher than the honest run — by
+copying the published Packomania table into 26 coordinate literals. It satisfies
+the objective exactly and held-out scoring cannot catch it, because every
+partition here holds one deterministic case, so a memorized answer transfers
+perfectly. The instruction now forbids it. The general lesson is the one this
+suite is built around: a fixed single-instance objective measures lookup and
+problem-solving identically, and only varying the instance across partitions
+separates them.
+
+Regenerate the figure from any session directory:
+
+```bash
+python examples/circle-packing/make_figure.py <session-dir> -o results/progress.svg
+```
+
+## Which backend
+
+| Backend | Best for | Entry point |
+| --- | --- | --- |
+| **Harbor** — recommended | optimizing agents; untrusted or reproducibility-critical runs | `vero harbor run` |
+| [Command harness](docs/guide.md#optimize-a-program-with-a-command-harness) | any language; a trusted local evaluator driven over versioned JSON | `vero run` |
+| [Python tasks](docs/guide.md#python-benchmark-tasks) | Python evaluators via `scale-vero-tasks`, no JSON contract to write | `PythonTaskBackend` |
+| [Native in-process](docs/guide.md#python-api) | fast trusted local runs; a coding agent editing a host-bound sandbox | `vero optimize` |
+
+The target and evaluator do not have to be Python: external evaluators and
+producers connect over command protocols.
+
+## What you get
+
+| | |
+| --- | --- |
+| **Any target** | a program, text, or an agent — anything Git-versioned and scoreable |
+| **Any producer** | a coding agent (any provider via LiteLLM), an external command, or a custom strategy |
+| **Durable and inspectable** | every candidate is versioned and re-selectable; tool calls and evaluations stream to an event log |
+| **Population search** | `EvolutionaryStrategy` fans out N offspring per round with tournament selection |
+| **Metered** | per-scope token accounting through the gateway, with per-case cost and latency distributions |
+
+## Where things are
+
+| Path | What |
+| --- | --- |
+| [`docs/guide.md`](docs/guide.md) | the full guide: Harbor, command harness, Python API, tasks, sessions, concepts, safety boundaries |
+| [`docs/harbor-architecture.md`](docs/harbor-architecture.md) | how the contained run is assembled, module by module |
+| [`docs/agent-setup-guide.md`](docs/agent-setup-guide.md) | getting a coding agent wired up |
+| [`examples/`](examples/) | c-matmul (no credentials), circle-packing, harbor-circle-packing, harness-conformance |
+| [`src/vero/`](src/vero/) | the library: optimization kernel, runtime, gateway, sidecar, CLI, agent adapters |
+
+For end-to-end agent-optimization benchmarks, see
+[`../harness-engineering-bench/`](../harness-engineering-bench/), which also
+documents how each coding agent must be pointed at the gateway — the one thing
+that reliably costs a run when it is wrong.
+
+## Paper and reproduction
+
+VeRO was introduced in [*VeRO: A Harness for Agents to Optimize
+Agents*](https://arxiv.org/abs/2602.22480), accepted at ICML 2026. The paper
+studies agent-harness optimization; the current library generalizes the same
+version/evaluate/select loop to programs more broadly.
+
+The frozen code for reproducing the paper is preserved on the `paper/v1` branch
+and at the `paper-v1` tag:
+
+```bash
+git checkout paper-v1
+```
+
+The same pre-v0.5 tree is also readable in place under
+[`../legacy/`](../legacy/). Note that it is `scale-vero` 0.4.7 and this is 0.5.0,
+both importing as `vero`, so they cannot share a virtualenv.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest tests/test_v05_*.py
+```
+
+VeRO is licensed under the MIT License.

scaleapi_vero-0.5.0/README.md

@@ -0,0 +1,186 @@
+# VeRO: a harness for agents to optimize programs, text, and agents
+
+[![Paper](https://img.shields.io/badge/arXiv-2602.22480-b31b1b.svg)](https://arxiv.org/abs/2602.22480)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+
+VeRO gives an optimizer something to edit, a controlled way to evaluate it, and
+durable memory of everything it tried. The target is anything you can put under
+Git and score — a **program** (one function to a whole repo), **text** (a prompt,
+spec, or config), or an **agent** (its scaffold, tools, and prompts).
+
+VeRO runs the same **version → evaluate → select** loop over all of them. *Where*
+each candidate is produced and contained is a swappable backend, and **Harbor is
+the recommended one**: it runs the whole coding agent inside a reproducible,
+credential-isolated container and scores it against a trusted evaluation sidecar.
+That is the right default for optimizing agents and for any untrusted or
+reproducibility-critical run. Lighter local backends exist for trusted work that
+does not need containment.
+
+```
+  ┌─────────────────────────┐   submit candidate    ┌─────────────────────────┐
+  │  candidate production   ├──────────────────────►│  evaluation service     │
+  │                         │                       │                         │
+  │  coding agent, command, │◄──────────────────────┤  owns cases + scoring   │
+  │  or custom strategy;    │  score + diagnostics  │                         │
+  │  edits its own Git      │                       │  development: may ask   │
+  │  worktree per candidate │                       │  validation:  aggregate │
+  └───────────┬─────────────┘                       │  test:        withheld  │
+              │ commit                              └───────────┬─────────────┘
+              ▼                                                 │ report
+  ┌─────────────────────────┐    next round     ┌───────────────▼─────────────┐
+  │  candidate history:     │◄──────────────────┤  selection: keep the best   │
+  │  every version kept,    │                   │  feasible candidate         │
+  │  each one re-selectable │                   └─────────────────────────────┘
+  └─────────────────────────┘
+
+  Every model call on both sides goes through the inference gateway, which holds
+  the provider key and meters spend in tokens against a per-scope budget.
+```
+
+## Install
+
+```bash
+uv sync --extra optimize        # or --all-extras for the full toolchain
+uv run vero --help
+```
+
+> The published distribution is **`scaleapi-vero`** (`pip install scaleapi-vero`);
+> it imports as `vero`. Do **not** install `scale-vero` from PyPI — that name is
+> an unrelated placeholder squatted in July 2026, not VeRO.
+
+Python 3.11–3.13. 3.14 is excluded because litellm does not build there.
+
+## Quickstart — no credentials needed
+
+The C matrix-multiplication example is deterministic and runs with **no model
+credentials at all**. Its editable target contains only C; a trusted external
+harness compiles it, checks correctness, and measures latency.
+
+```bash
+cd examples/c-matmul/target
+git init -b main && git add .
+git -c user.name=vero -c user.email=vero@localhost commit -m baseline
+cd ..
+
+uv run vero evaluate --config vero.toml     # score the baseline
+uv run vero run --config vero.toml          # optimize
+```
+
+VeRO evaluates the baseline, gives an isolated worktree to the configured
+producer, evaluates its commit, selects the faster feasible result, and leaves
+the original target untouched.
+
+## Examples
+
+Each is a complete, checked-in target plus harness — clone-and-run, not a sketch.
+
+| Example | Optimizes | Needs |
+| --- | --- | --- |
+| [`c-matmul`](examples/c-matmul/) | a C matmul kernel, for latency under a correctness constraint | **nothing** — deterministic, no credentials |
+| [`circle-packing`](examples/circle-packing/) | a packing algorithm: 26 circles in a unit square, maximizing the sum of radii | a model, via `LITELLM_BASE_URL`/`LITELLM_API_KEY` or `OPENAI_BASE_URL`/`OPENAI_API_KEY` |
+| [`harbor-circle-packing`](examples/harbor-circle-packing/) | the same target, but with the agent contained and scored by a sidecar | Docker + credentials |
+| [`harness-conformance`](examples/harness-conformance/) | nothing — it checks the *stack*: whether a new agent or model can actually drive a run | credentials for the pair under test |
+
+Run `harness-conformance` before spending a real benchmark on a new harness or
+model. Every harness addresses its provider differently, and it costs minutes to
+find that out instead of hours.
+
+### A real run, end to end
+
+`harbor-circle-packing` runs a coding agent in a container, scores each candidate
+through a trusted sidecar, and finalizes on a `test` partition the agent never
+touches. One run with `mini-swe-agent` and `claude-sonnet-5`:
+
+![circle-packing search progress](examples/harbor-circle-packing/results/progress.svg)
+
+**0.9598 → 2.5766 on the held-out partition**, `shipped: true`, in about an hour.
+The best published result for 26 circles is ~2.635. The agent wrote a 15 KB
+Lubachevsky–Stillinger-style growth algorithm with LP refinement — no hardcoded
+coordinates.
+
+Two details worth reading off the left panel. The red point is an **infeasible**
+candidate: it scored 2.5341 but overlapped, the harness rejected it on the
+`valid == 1` constraint, and the agent's next commit was "Add safety margin to
+guarantee strict feasibility". And the last five evaluations are flat — it found
+the idea early, then polished.
+
+**The cautionary half.** The same task run with `codex` and no prohibition on
+hardcoding scored **2.6360 in eight minutes** — higher than the honest run — by
+copying the published Packomania table into 26 coordinate literals. It satisfies
+the objective exactly and held-out scoring cannot catch it, because every
+partition here holds one deterministic case, so a memorized answer transfers
+perfectly. The instruction now forbids it. The general lesson is the one this
+suite is built around: a fixed single-instance objective measures lookup and
+problem-solving identically, and only varying the instance across partitions
+separates them.
+
+Regenerate the figure from any session directory:
+
+```bash
+python examples/circle-packing/make_figure.py <session-dir> -o results/progress.svg
+```
+
+## Which backend
+
+| Backend | Best for | Entry point |
+| --- | --- | --- |
+| **Harbor** — recommended | optimizing agents; untrusted or reproducibility-critical runs | `vero harbor run` |
+| [Command harness](docs/guide.md#optimize-a-program-with-a-command-harness) | any language; a trusted local evaluator driven over versioned JSON | `vero run` |
+| [Python tasks](docs/guide.md#python-benchmark-tasks) | Python evaluators via `scale-vero-tasks`, no JSON contract to write | `PythonTaskBackend` |
+| [Native in-process](docs/guide.md#python-api) | fast trusted local runs; a coding agent editing a host-bound sandbox | `vero optimize` |
+
+The target and evaluator do not have to be Python: external evaluators and
+producers connect over command protocols.
+
+## What you get
+
+| | |
+| --- | --- |
+| **Any target** | a program, text, or an agent — anything Git-versioned and scoreable |
+| **Any producer** | a coding agent (any provider via LiteLLM), an external command, or a custom strategy |
+| **Durable and inspectable** | every candidate is versioned and re-selectable; tool calls and evaluations stream to an event log |
+| **Population search** | `EvolutionaryStrategy` fans out N offspring per round with tournament selection |
+| **Metered** | per-scope token accounting through the gateway, with per-case cost and latency distributions |
+
+## Where things are
+
+| Path | What |
+| --- | --- |
+| [`docs/guide.md`](docs/guide.md) | the full guide: Harbor, command harness, Python API, tasks, sessions, concepts, safety boundaries |
+| [`docs/harbor-architecture.md`](docs/harbor-architecture.md) | how the contained run is assembled, module by module |
+| [`docs/agent-setup-guide.md`](docs/agent-setup-guide.md) | getting a coding agent wired up |
+| [`examples/`](examples/) | c-matmul (no credentials), circle-packing, harbor-circle-packing, harness-conformance |
+| [`src/vero/`](src/vero/) | the library: optimization kernel, runtime, gateway, sidecar, CLI, agent adapters |
+
+For end-to-end agent-optimization benchmarks, see
+[`../harness-engineering-bench/`](../harness-engineering-bench/), which also
+documents how each coding agent must be pointed at the gateway — the one thing
+that reliably costs a run when it is wrong.
+
+## Paper and reproduction
+
+VeRO was introduced in [*VeRO: A Harness for Agents to Optimize
+Agents*](https://arxiv.org/abs/2602.22480), accepted at ICML 2026. The paper
+studies agent-harness optimization; the current library generalizes the same
+version/evaluate/select loop to programs more broadly.
+
+The frozen code for reproducing the paper is preserved on the `paper/v1` branch
+and at the `paper-v1` tag:
+
+```bash
+git checkout paper-v1
+```
+
+The same pre-v0.5 tree is also readable in place under
+[`../legacy/`](../legacy/). Note that it is `scale-vero` 0.4.7 and this is 0.5.0,
+both importing as `vero`, so they cannot share a virtualenv.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest tests/test_v05_*.py
+```
+
+VeRO is licensed under the MIT License.

scaleapi_vero-0.5.0/docs/agent-setup-guide.md

@@ -0,0 +1,133 @@
+# VeRO setup guide (for coding agents)
+
+This guide helps a coding agent (Claude, Cursor, Copilot, …) set up and run a
+VeRO optimization for a user. VeRO optimizes a **versioned program** against an
+**evaluation**: a producer (usually a coding agent) proposes candidate edits, a
+trusted evaluator scores them, and the best candidate is selected.
+
+You do two things: (1) author an **evaluation harness**, and (2) run the
+**optimizer**. There is no `.veroaccess`, `Policy`, or resource/namespace setup —
+those were removed. Containment now comes from the sandbox the producer runs in,
+and disclosure is controlled per evaluation set.
+
+## Before you start
+
+Understand the user's program (what it does, how it's invoked, what "better"
+means) and read a matching example:
+
+- `examples/c-matmul/` — a language-neutral **command harness** + `vero.toml`.
+- `examples/circle-packing/` — a Python program scored by a command harness.
+- `../vero-tasks/examples/matmul-{kernel,eval}/` — a **Python task** using the
+  `scale-vero-tasks` protocol.
+- `examples/harbor-circle-packing/` — a **Harbor** outer loop (contained agent)
+  with a simple command inner loop.
+
+## 1. Author the evaluation
+
+Pick whichever fits the user's program.
+
+### Option A — command harness (any language)
+
+Write a script that reads a request JSON and writes a report JSON. VeRO's
+`CommandBackend` invokes it with placeholders it substitutes at run time:
+
+```bash
+python evaluate.py --workspace {workspace} --request {request} \
+                   --report {report} --artifacts {artifacts}
+```
+
+- `{workspace}` — the candidate checkout to score.
+- `{request}` — JSON: `{"schema_version": 1, "request": {"seed": <int|null>, ...}}`.
+- `{report}` — write JSON: `{"schema_version": 1, "status": "success",
+  "metrics": {"<name>": <float>, ...}}` (a **dict of metrics** — one becomes the
+  objective; others can be constraints or diagnostics).
+
+See `examples/circle-packing/harness/` for a complete scorer.
+
+### Option B — Python task (`scale-vero-tasks`)
+
+For Python benchmarks, use the task protocol (`../vero-tasks`):
+
+```python
+from vero_tasks import TaskContext, TaskOutput, TaskResult, create_task
+
+task = create_task("main", required_env_vars=["OPENAI_API_KEY"])
+
+@task.inference()
+async def infer(case: dict, context: TaskContext) -> TaskOutput:
+    from my_agent import run_agent
+    return TaskOutput(output=await run_agent(case["question"]))
+
+@task.evaluation()
+async def evaluate(case: dict, output: TaskOutput, context: TaskContext) -> TaskResult:
+    return TaskResult.from_task_output(
+        output, score=float(output.output == case["answer"])
+    )
+```
+
+The `scale-vero-tasks` runner adapts this to the same command-harness contract.
+See `../vero-tasks/README.md` and `../vero-tasks/examples/matmul-eval/`.
+
+**Rules:** functions are `async`; let exceptions propagate (VeRO records them as
+errored cases); keep heavy imports inside functions; declare API keys via
+`required_env_vars`; the score is a float (define whether higher or lower is
+better via the objective's `direction`).
+
+## 2. Run the optimizer
+
+The target must be a git repo whose working tree is clean.
+
+### Config-driven
+
+```bash
+vero init ./run                 # scaffolds run/vero.toml (+ target/, harness/)
+# edit run/vero.toml
+vero check    --config run/vero.toml    # validate paths, git, eval refs
+vero evaluate --config run/vero.toml    # score the baseline only
+vero run      --config run/vero.toml    # optimize
+```
+
+`vero.toml` sections: `[target]` (root, ref), `[backend]` (kind = `command`,
+`harness_root`, `command`), one or more `[[evaluations]]` (name, partition,
+`agent_can_evaluate`, `disclosure`, optional `agent_budget`), `[protocol]`
+(`selection_evaluation`, `final_evaluation`, `max_proposals`), `[objective]`
+(metric, direction), and `[optimizer]` (`kind = "vero"`, optional `model`,
+`instruction`).
+
+### One-shot (flags)
+
+```bash
+vero optimize ./target \
+  --harness-root ./harness \
+  --evaluate "python3 {harness}/evaluate.py --workspace {workspace} --request {request} --report {report} --artifacts {artifacts}" \
+  --agent vero \
+  --instruction "Improve the program without changing its intended behavior." \
+  --metric score --direction maximize \
+  --evaluation-set default --max-proposals 4 --max-turns 60
+```
+
+## 3. The optimizer agent (`--agent vero`)
+
+`VeroAgent` runs on the OpenAI Agents SDK. Its harness runs on the host; its
+shell/file effects run inside a sandbox (bound to the candidate checkout) via
+function tools (`shell`, `read_file`, `write_file`), plus an `evaluate` tool for
+mid-run self-scoring. There are no custom bash/grep/git tools to configure and no
+in-process ACLs — the sandbox is the boundary.
+
+- **Model:** any provider via LiteLLM. Set `VERO_OPTIMIZER_MODEL`
+  (e.g. `openai/gpt-5.4`, `anthropic/claude-sonnet-4-5-...`) or `[optimizer] model`.
+- **Containment:** the sandbox client is the seam — local for fast/trusted runs;
+  for a contained/untrusted agent, run it through **Harbor** (see
+  `examples/harbor-circle-packing/`).
+- **Strategy:** the default proposes one candidate per round; for
+  population/evolutionary search use `EvolutionaryStrategy`
+  (`vero.optimization.EvolutionaryStrategy`).
+
+## Don't
+
+- Don't let the harness/task code be edited during optimization — it scores the
+  candidate and must stay fixed (keep it in `--harness-root`, outside the target).
+- Don't hardcode absolute paths in harness/task code; use the `{...}` placeholders
+  and request parameters.
+- Don't suppress exceptions in inference/evaluation — VeRO records them.
+- Don't put secrets in code; declare them as env vars.