Playbooks

A playbook lives at <project>/com.artek.artekis/playbooks/<name>/playbook.json and is edited in the views pack's Artekis/Admin/Playbooks view (/artekis/admin/playbooks, admin level) as a form or as JSON, or written by system.artekis.playbooks.put. Playbooks are read from every project on the gateway.

{ "template": "alarm-health@1", "enabled": true, "collections": ["line2"],
  "triggers": [ { "type": "cron", "expr": "0 5 * * 1", "window": { "value": 7, "unit": "DAYS" } },
                { "type": "script" } ],
  "params": { "shiftStarts": ["06:00", "18:00"] },
  "budget": { "maxOutputTokens": 16000, "maxUsdPerRun": 1.0 },
  "suppression": { "confidenceFloor": 0.5, "repeatWindowHours": 24 },
  "outputs": { "perspectiveMessage": { "type": "artekisFinding", "scope": "session" },
               "email": { "profile": "Plant", "from": "artekis@plant.example", "to": ["ops@plant.example"],
                          "on": ["severity>=high"] } },
  "description": "Weekly Alarm Health for Line 2" }

Key	Meaning
template	alarm-health@1, gateway-health@1, incident@1, ask@1, anomaly-watch@1 or mes-watch@1
enabled	default false
collections	collection ids; each needs a context model (gateway needs none)
triggers	cron (expr five fields, in the settings timezone; missed minutes are not replayed; window sets the span analysed, default 7 days for Alarm Health and 24 h for Gateway Health), event (with an optional kind, fired by system.artekis.trigger or an Event Stream), script (fired by runPlaybook). An ask@1 playbook is never started by either: an event lists it as REFUSED and runPlaybook refuses it; Ask runs through system.artekis.ask and the Ask panel
roles	point one of the template's roles at another of the provider's roles, by name — {"writer": "triage"} sends this playbook's writer calls to the provider's triage model. A model id here is read as a role name and the run fails "no model configured for role …"; models are set on the provider (section 6.1)
budget	maxInputTokens (the evidence bundle is cut to fit), maxOutputTokens (default 16,000), maxUsdPerRun, candidatesPerCall (Anomaly Watch, MES Watch and Alarm Health, default 12, Alarm Health 6, 1–200: a run with more candidates calls the writer once per batch, each call seeing only its batch's candidates and their evidence; the answers are validated together, each call checked against what is left of maxUsdPerRun, and if a later batch fails or the budget runs out the candidates not yet written keep the check's own text. A batch whose call times out is split in half and retried, down to one candidate, untried batches first; every call is sized to end before the playbook's timeoutSeconds, and a later batch is not started with under 45 s left; a timeout ends the run only when no call answers. Give a playbook a timeoutSeconds well above the provider's call timeout so a split has time to run)
suppression	confidenceFloor (findings below it are stored hidden, default 0.5), knownIssueDays (30), dismissDays (90), repeatWindowHours (how long before an open finding is announced again, 24)
debounceSeconds	triggers for the same collection and asset within it are merged (default 120)
ratePerHour	runs per hour per playbook (default 60)
timeoutSeconds	the whole run (default 300; a timeout that lands after the run started storing lets it finish and the run ends DONE with a note)
params	template-specific thresholds (below)
outputs	where findings are announced (section 9)

A run is queued (at most maxConcurrentAnalyses run at once, one run per collection at a time, 200 waiting) and ends in one of four states: DONE; SKIPPED (cap, no-collection, ai-cutoff, licence, no-provider); FAILED (credential, timeout, restart, or the error); REJECTED (parse — the model's answer was not the contract's shape, truncated — it hit the output budget, refusal). Only a DONE run stores findings and resolves old ones. The Status page shows each playbook's last run and the findings the validator dropped, with the rule.

When a finding closes. A DONE run resolves the findings of its own playbook and collection it no longer produces, within what it looked at, and every finding it resolves carries a Why this finding was resolved item (evidence ev:resolved:why, shown as a sentence on the finding page) with one of these reasons:

Reason	When
not-found	the run looked (Anomaly Watch: over its window) and did not find it
fire-passed	a past detector fire, not filed by any run for 7 days (time for a verdict), then a scheduled screening run that evaluated the detectors found no fire over it (a fire on a tag whose source failed is held). A detector proposal, a manual run or a replay never resolves a fire. A resolved fire can still be judged; its verdict sets its status, counts in the detector's hit rate and removes the resolved reason
stretch-passed	Anomaly Watch: a scheduled run, and the finding's span ended before the run's window and it has gone 24 hours unseen (a row a manual run, a replay or a backtest filed over an earlier stretch). A manual run never resolves a row from a window it did not read. A drift, quality, rate, per-run or setpoint anomaly still going within 72 hours continues the row instead; any other that comes back is filed as a new finding
not-screened	Anomaly Watch: a scheduled run, and the playbook no longer runs the finding's check or no longer screens its machine
quiet	Alarm Health: none of the finding's alarms went active for 28 days (a quieter stretch keeps it open); never an alarm the live status shows active, never after a journal read that was cut short, without the live status, or in a run whose window ended more than a day ago
fell-back	Anomaly Watch: a trend whose reading fell back to its level before the climb
within-band	Anomaly Watch: a trend now small against its setpoint band; its note is kept beside it
not-checked	Anomaly Watch, a station condition of the pump check or a controlled loop of the setpoint check: the station or loop could not be checked (deadline, failed read, too little data) for more than 72 hours after its finding's last span; within 72 hours the open finding is held

Never resolved on absence: a confirmed finding (its verdict stands), and an Anomaly Watch finding a run still holds (a trend or drift whose standing it could not tell, section 8.5). A resolved finding found again opens again in place.