--- title: "The field-theory lab: a theory derived, solved, weighed and collided, with an honesty box." method: POST path: "/api/agents/run/pull_lab" tags: ["Lab"] --- # The field-theory lab: a theory derived, solved, weighed and collided, with an honesty box. `POST /api/agents/run/pull_lab` ## Request - Base URL: `https://tomorrowlives.com` - URL: `https://tomorrowlives.com/api/agents/run/pull_lab` - Auth: HTTP bearer Runs the pull engine's field-theory lab on a theory document (its fields, Lagrangian, which quantity is the mass, what fixes the sector and the value expected; pull_schema lists the keys): the equations derived, a static solution found and weighed, a check that the solver finds no lump where there is none, its small oscillations and a collision, in a fixed layout with an honesty box saying what is exact and what is remembered rather than sourced. reference (true, or a reference theory's name) runs the reference suite instead, each known number naming its source. reference true (the one-dimensional suite) answers within 30 seconds for 1 unit. A one-dimensional theory is counted first, by the engine, in its sites and its relaxation and collision steps: one that comes to 1 unit (a second or so, on the lattice the lab picks for most theories) answers at once for that unit, and a larger one is queued and priced like a theory with a model, at least 1 unit. The lab picks a spacing of 0.05 over the heavier meson and a box of 16 over the lighter, so a theory whose vacua differ a hundredfold in mass counts 64,001 sites and some 3,200 CPU-seconds, and a lattice the theory sets itself (lattice.dx as fine as 1e-4, lattice.half_length as wide as 1000) grows as the square of one over the spacing. A theory with a model (the Skyrme model's baryon, the Faddeev-Skyrme model's knot), and reference skyrme or hopfion, relaxes a lattice in three dimensions, which takes minutes of CPU: it is queued, on 4 threads, and priced by the engine's count of its lattice and steps, a unit for each 5 CPU-seconds of one thread it estimates, at least 1 and at most 300 (the reference Skyrmion costs 38; a hopfion relaxes four times, and the reference one, on 128 sites a side, comes to far over the most a job may cost and is refused with its price, while one relaxed on 64 sites a side, 217 units, is accepted; pull_cost says the price first). The steps priced are the steps asked for or, for each site of the relaxed lattice's side less one, 60 (a Skyrmion) or 75 (a hopfion), whichever is fewer, which is more than a relaxation took in a box that holds the soliton (a Skyrmion's 25 to 43 for each side less one at 25 to 161 sites a side, a hopfion's 28 to 56 at 32 to 128); a box narrower than the soliton (a Skyrmion's lattice.half_length must be 2 or more, a hopfion's relax.half_length 4 or more), where a relaxation took several times as long or never settled, is refused, and a relaxation that has not settled by then is stopped at three times its estimate and costs its price. A call priced at more than 2 units is queued: the answer is 202 with a job id and its price, GET /api/agents/jobs/ (or the MCP tool job) says when it is done, and the whole report comes back as report.json beside a short verdict. A queued call is refused on the free plan with 402: its units buy only calls that answer at once, and queued jobs need a paid plan (a pass or the card plan). ## Request body - object - `theory` object: The theory document written inline: its fields, Lagrangian and the quantity to match. - `reference` union: True, or a reference name, to compare against a reference run. - true - string ## Response `200` The job's result and files - Job - `job` string - `verb` string - `units` integer - `ms` integer - `result` unknown - `files` object[] - `name` string - `bytes` integer - `content_type` string - `url` string - `url_expires_at` string, date-time ## Other responses - `202`: Queued: the job id, its price and where to poll. Poll GET /api/agents/jobs/{job} until it is ok, refused or failed. - `400`: The input is not valid - `401`: No valid API key - `402`: A pass or a payment is needed: a queued render on the free plan, a unit pack on the free plan (pass_required), a card plan's past-due renewal, or, on the free plan, an owner who has not confirmed their email yet (owner_unconfirmed; a pass needs no confirmation); or a payment did not go through (payment_failed, payment_token_unusable), and nothing was charged - `403`: The account is suspended, the paying card is not from the United States (region_not_supported), or the address named as its owner said it is not theirs and costed runs are paused until a new owner is named (owner_removed) - `413`: The input or the output is over its cap; a job stopped by the output cap is not charged - `422`: The engine refused the input, a limit of the service's refused it (error: video_limit or pull_limit) or stopped the job, or the content policy refused the input (error: content_policy) - `429`: A limit was hit; reset_at says when it lifts (also in Retry-After) - `503`: The engines are busy or not installed - `504`: The job ran past its time and was stopped --- [API](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines.md) · [All operations](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/llms.txt) · [OpenAPI document](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/revisions/afc3d67322ac?raw)