Writing templates¶

Your own server can set up checks, as well as read them. A template goes live in four steps, each its own call, so a person can read each answer before the next step:

1. Save a draft. A new template, or the next version of one.
2. Preview it on your recent jobs, beside the version that is live now.
3. Make it live. Every new job uses it; a job already started keeps the version it started with.
4. Roll back, if you need to, by making the version before it live again.

The key needs the Check templates permission, chosen when the key is made at Company → API keys. A key that only sends photos cannot write templates or change their settings.

In the console: the rule builder¶

Owners and admins can do the same without writing JSON, at Company → Rule sets. Open a rule set, or choose New rule set:

• Photos: the photos a job sends, by name. Mark the ones a job must send as Needed.
• Checks: each one reads as a sentence of choices, for example At least [1] [hard_hat], None of [open_trench], or Every [person] has a [hard_hat] on it. Choose Add a condition to combine conditions: Pass when [all / any / at least N / none] of these, and Add a group for one more level (at most three, counting the choice of photos).
• If this fails: fail the job, send the job to a person, or just note it.
• If Sight can't see it clearly: send to a person, or fail the check.
• Tell the person taking the photo: what to do when it fails.

Sight says each check back in plain words as you build. It also lists anything that would stop the rule set being saved, such as a thing your models have not learned. Then the same four steps follow:

1. Save draft.
2. Preview on recent jobs.
3. Make live…, after a confirmation.
4. Make an older version live the same way to roll back.

Parts the builder cannot change yet, such as readings and settings, are shown as A condition the builder cannot change yet. They are kept exactly as they are when you save. A rule set written in the first rule format moves to the current one when you save it here. Preview it before making it live: any job whose result would change is listed.

You can also put this builder inside your own app, for your customers: see The rule builder in your app.

Routes¶

A reseller writes for an account it sells to by adding "account": "<the client's account id>" to the body (or ?account= to a GET), on every route above, settings included. A key can never write for an account above its own or beside it: that answers 404, the same as an account that does not exist.

1. Save a draft¶

curl -X POST https://sightapi.raku.so/checks/templates \
  -H "X-Api-Key: $SIGHT_API_KEY" -H "Content-Type: application/json" \
  -d '{"definition": {"key": "site-completion", "name": "Site complete", "slots": ["front_view"],
       "checks": [{"key": "door_present", "name": "Front door in the photo",
                   "photos": {"slot": ["front_view"]},
                   "rule": {"find": {"class": "front_door"}, "count": {">=": 2}}}]}}'

The answer (201) is the version, numbered by Sight (one more than the last), with status: "draft" and each check in plain English (sentence, details). No job uses a draft.

It is checked first, exactly as every other way of saving a template checks it: its shape, that every class is one your model has learned and every slot one the template lists, and that your plan includes it (rules that combine conditions are part of the paid plans). If anything is wrong the answer is 422 (or 402 for the plan) with a sentence saying what and where, and nothing is saved.

2. Preview it¶

curl -X POST https://sightapi.raku.so/checks/templates/site-completion/versions/3/preview \
  -H "X-Api-Key: $SIGHT_API_KEY" -H "Content-Type: application/json" -d '{"jobs": 50}'

{
  "version": 3, "against_version": 2,
  "summary": "On 50 recent jobs, version 3: 41 pass, 3 fail, 6 go to a person. Live version 2: 44 pass, 0 fail, 6 go to a person. 3 verdicts would change.",
  "jobs_compared": 50, "jobs_skipped": 0,
  "verdicts_draft": {"pass": 41, "fail": 3, "needs_review": 6},
  "verdicts_live": {"pass": 44, "needs_review": 6},
  "verdicts_changed": 3,
  "examples": [{"job_id": "1f0c…", "external_id": "task-42", "live": "pass", "draft": "fail"}],
  "checks": [{"key": "door_present", "status": "changed", "live": {"pass": 50}, "draft": {"pass": 47, "fail": 3},
              "changed": 3, "examples": [...]}],
  "waiting_for_a_reading": 0,
  "model_calls": 0
}

Each recent job of this template is judged twice, with this version and with the live one, from what was already seen and read on its photos. The model and the reader are never asked again, so a preview costs nothing and counts against no allowance. Two things it cannot know, and says so:

• A job whose photos the model never looked at for these checks (say this version looks for something in a slot the live version only read) is left out, listed in skipped with why, rather than counted as a fail.
• A check that needs a reading that was never made comes out pending (waiting_for_a_reading); a live job would ask for it.

Every preview is kept.

3. Make it live¶

curl -X POST https://sightapi.raku.so/checks/templates/site-completion/versions/3/activate \
  -H "X-Api-Key: $SIGHT_API_KEY"

{"key": "site-completion", "version": 3, "previous_version": 2, "changed": true, "rollback": false}

• A draft goes live only after a preview against the version it replaces; otherwise the answer is 409 and nothing changes. If another version was made live in the meantime, preview again.
• If that preview could judge none of the recent jobs it found (each would have needed the model), it has shown nothing, so it goes live only when you send {"confirm_untested": true}; your company's activity records that you did.
• It is checked again as it stands today (your plan or your model may have changed since it was saved), and refused with a sentence if it no longer passes.
• The version live before is retired, never deleted. A job already started keeps the version it started with; every result names its version.

4. Roll back¶

Make the earlier version live again. It was live before, so it needs no new preview; it is still checked as it stands today.

curl -X POST https://sightapi.raku.so/checks/templates/site-completion/versions/2/activate \
  -H "X-Api-Key: $SIGHT_API_KEY"

Every save and every activation is recorded in your company's activity, with the key that made it.