# infini.build verification API — agent guide (v0.1)

Base URL: `https://verify.infini.build`
Auth: every `/v1/projects*` and `/v1/jobs*` call needs `Authorization: Bearer <API key>`.

You design hardware as a **Python design program**; the service builds it (sandboxed), simulates it
and returns an objective verdict per requirement, a score, issues with fixes, and sensitivities.
You iterate: edit only the files that changed, or just change parameters, and evaluate again.

## 1. Workflow

1. `GET /v1/categories` → pick a category. `GET /v1/categories/{name}` → scorecard and a full example design program.
2. `GET /v1/tasks/{task_id}` → the task (requirements, objective). Example tasks: `fw-001`, `pp-001`, `fl-001`.
3. `POST /v1/projects` `{"name": "...", "category": "fixed_wing"}` → `{"id": "p_..."}`.
4. `POST /v1/projects/{pid}/commit` with only the changed files:
   ```json
   {"message": "first wing", "changes": [{"path": "design.py", "content": "<python source>"},
                                        {"path": "parts/wing.py", "content": "..."},
                                        {"path": "assets/pod.step", "content_b64": "..."},
                                        {"path": "old.py", "delete": true}]}
   ```
   Files not listed are kept from the previous revision. Returns the new revision id.
5. `POST /v1/projects/{pid}/evaluate?wait=120`
   ```json
   {"task": "fw-001", "params": {"span": 1.0}, "fidelity": "V1", "mc_samples": 16, "sensitivity": true}
   ```
   `params` override `PARAMS` defaults **without a new commit** (fast design-space exploration).
   Add `"brief": "..."` to say in plain language what the simulation should focus on (see §5).
   With `wait` the call returns the finished report when it completes within the wait; otherwise poll
   `GET /v1/jobs/{job_id}`.
6. Read `report`, change parameters or files, evaluate again. Unchanged geometry and analyses are cached.

## 2. Design program contract

`design.py` (or `entry`) must define:

```python
from vlayer.core.design import Design, Param, Part, Component, Port
PARAMS = {"span": Param("0.9 m", ("0.6 m", "1.2 m"))}      # name -> default, range, unit
def build(p):                                             # p.span etc. are SI floats
    d = Design("my_design", category="fixed_wing")
    ...
    return d
```

- `build` must be a pure function of the parameters.
- The program runs **without network**, with a read-only file system except its own working dir; other files of
  your project are importable (`from parts.wing import half_wing`).
- Geometry: write CAD with **build123d** (mm, assembly frame: x aft, y right, z up), or import STEP from your
  project (`Part(..., step="assets/x.step")`).
- Semantics (materials, processes, joints, mounts, loads, lifting surfaces, …) follow
  `GET /v1/docs/semantics`. Library items: `GET /v1/library/{motor|prop|battery|esc|servo|electronics|material}`.

### Category-specific building blocks

| Category | Import | Required semantics |
|---|---|---|
| `fixed_wing` | `vlayer.fixed_wing`: `LiftingSurface`, `Section`, `ControlSurface`, `Spar`, `tag_lifting_surface` | lifting surfaces (primitive or tagged CAD), pitch + roll control, one motor/prop/battery |
| `printed_part` | `vlayer.core.physics`: `Mount`, `Load`; `vlayer.core.selectors`: `Region` | `Part(process={"type": "fdm", "build_dir": "+z", "infill": 0.3})`, ≥1 `Mount` and ≥1 `Load` |
| `mechanism` | `vlayer.core.physics`: `Joint`, `Drive`; `vlayer.mechanism`: `Output`; `Axis` | parts connected to `"world"` by joints, one `Drive`, one `Output` |

Regions and axes are in **meters**, CAD in **millimeters**.

## 3. Reading the report

- `verdicts[]`: per requirement `PASS` / `FAIL` / `UNVERIFIABLE`. `UNVERIFIABLE` always has `reason.kind`
  (`missing_semantics`, `out_of_domain`, `invalid_ir`, `needs_higher_fidelity`, `not_implemented`, or
  `internal_error` — a server-side solver failure, not your design's fault; retry later) and
  `reason.detail` telling you exactly what to add or change.
- `score.total` (0–100, 0 when a gate fails), `score.dims` (function, experience, manufacturability, cost, assembly),
  `score.gates[]`.
- `issues[]`: `severity`, `target` (part / component / param), `rule`, `actual`, `cause`, `suggestion`. Fix
  `blocking` issues first.
- `sensitivity`: d(metric)/d(param) in SI units for the objective and for failed requirements — use it to choose
  the next parameter change.
- `metrics`: every computed quantity with unit, confidence (0–1) and Monte Carlo q10/q90.
- `next`: a one-line suggestion.

If the job fails, `error.stage` is `design_program` (your code raised — see `error.traceback`) or `evaluation`.

## 4. Fidelity

- `V1`: fast models (seconds to a minute). Use for iteration.
- `V2`: finer meshes, more cycles, a second FEA solver cross-checks the first; slower. Use to confirm a candidate.
- V3 (real manufacturing) is not open yet.

## 5. Simulation briefs: telling the service what matters

Put your user's priorities and conditions into `brief` (any language, ≤ 4000 characters), e.g.
`"It must survive a 5 g pull-up. Weight matters more than cost. Endurance must be at least 15 min even in the worst 10% of builds."`
The service reads it into a **plan** and uses only what the category's reviewed standard offers:

- `requirements`: extra pass/fail checks on the standard's metrics (ids `B1`, `B2`, …, next to the task's `R*`);
- `scenario`: values for parameters the standard marks adjustable, inside the range experts approved
  (e.g. fixed-wing `load_factor` 2–8 g, `hand_launch_speed_ms`, `battery_reserve`);
- `focus`: metrics reported first in `report.focus`;
- `run`: fidelity, Monte Carlo samples, sensitivity (fields you set explicitly in the request win);
- `unsupported`: what you asked for but nothing can verify yet — tell your user; it will not be silently ignored.

A brief never changes the standard's thresholds or models. `POST /v1/plan` `{"category": "...", "task": "fw-001",
"brief": "..."}` previews the plan and lists the metrics and adjustable parameters; send it back unchanged as `"plan"` in
`evaluate` to run exactly that plan, or set `"scenario": {...}` directly. Every report includes the `plan` it used.

## 6. Working with your user

- Read the API key from `INFINI_API_KEY` (or wherever your user put it); never print, log or commit it.
- Iterate with `V1` (turn `sensitivity` off or lower `mc_samples` when you only need a quick check); confirm the
  final candidate with `V2`.
- After each iteration tell the user what you changed, how the score and each requirement moved, and what you
  will try next. Stop and ask when the goal is met or several iterations make no progress.

## 7. Environment standards and expert review

Every category is backed by a written standard: all constants, thresholds, score anchors, Monte Carlo
parameters and assumptions, each with its source. The evaluators read their values from it.

- `GET /v1/envs` → each environment's `standard_version` (content hash) and `review_status`
  (`draft`, `needs_re_review`, `conditionally_approved`, `approved`, `rejected`) and how many values are still placeholders.
- `GET /v1/envs/{name}/card` → the human-readable standard card. `GET /v1/envs/{name}` → the same as JSON, plus reviews.
- Every report has `environment: {name, standard_version, review_status, placeholders}`. Tell your user when a
  result comes from an environment that is not yet `approved`.
- Domain experts with an expert key review via `POST /v1/envs/{name}/reviews`
  (`standard_version`, `reviewer`, `verdict`, `checklist`, `conditions`, `comments`, `param_comments`).
  A review only counts for the version it names; any change to the standard needs a new review.

## 8. Limits (v0.1)

≤ 4 active jobs per key, ≤ 20 MB per file, ≤ 200 MB per project, design program ≤ 300 s and 6 GB.
Library data, material data and thresholds are **placeholders**: scores are for relative comparison only.