system.artekis.*

Registered in the gateway (where it runs, Perspective included) and in the Designer (autocomplete and docs; each call is forwarded to the gateway). Keyword arguments; results are plain dicts and lists; timestamps are UTC ISO-8601 text. name is <project>/<name>, or <name> in the calling project.

Function	Returns
runPlaybook(name, event=None)	{runId, queued, reason, runs}: the playbook needs a script trigger; returns at once. An ask@1 playbook is refused (use ask)
runPlaybookAndWait(name, event=None, timeout=120)	{runId, state, error, findingIds, findings}: gateway scope only
trigger(event)	{queuedRuns, runs}: every runnable playbook with an event trigger on event["collection"] whose kind matches; with event["playbook"] (project/name, or the name alone) only that playbook, and a name that takes no such event is refused naming it. at (ISO-8601) sets the end of the window a run analyses, window ({value, unit: MINUTES|HOURS|DAYS}) its length: a manual run over a past stretch
getRun(runId)	the run row, its findingIds and, for Ask, answer; None if unknown
getFindings(filter=None, page=0, size=50)	{rows, total, page, size, filter}; filter keys collection, asset, playbook, severity, status, since, until, text, family (a list of drift, trend, setpoint, band, stuck, rate, runs, part-share, part-mean, part-stuck, quality, data-health, detector-fire; the Anomaly Watch families, system.artekis.access's anomalyFamilies), and group: with group: true, live findings of one playbook with the same family, the same tag name and span starts within 60 minutes, on two or more assets, come back as ONE row (the newest member's, plus assets, memberIds, groupSize, groupKind: "assets"), and the detector-fire rows of one detector waiting for review or judged real or known (each carries detectorIds, the detectors its evidence names; a fire whose detectors could not be read groups by its tag) with the same playbook, asset and status, however far apart, come back as ONE row too: a fire never joins the across-assets group (the newest fire's, its title counting the fires ("Detector fired 23 times: DCM-203 fill time high, Oct 28 to Nov 6") plus groupKind: "fires", fireCount, groupSize, memberIds newest first, assets, firstFire and lastFire (the earliest and latest fire start), firstSeen the earliest member's and seenCount the highest; its cost adds its fires' prices, each over its own span and like kinds only, with since and until null and a basis saying so); group: "fires" groups only the fires; without sort: "cost" a grouped read prices only the rows of the page asked for; total and paging count those rows; each asset and each fire keeps its own stored finding, verdict and hit-rate count; sort: "lastSeen" (default, newest first), "severity" (worst first, then newest, over the newest 1,000 matches, severityScanCut true when more matched, the Findings list's order) or "cost" (attributed rows by amount, then above-normal rows by amount, then mixed groups, risks and the rest, newest first; ranks the newest 1,000 matches, costScanCut true when more matched); every row carries cost {amount, currency, kind, kindText, downtimeMinutes, scrapParts, scrapByProduct, byKind, partial, since, until, basis, measure, missing, reason, figure, arithmetic, text, label} (section 7.8; since when it began before first seen, until when its span ended before its last sighting, measure for an MES Watch excess; a group's since is its members' earliest when every member has one, its until their latest when every member has one, else null), a group's summed over its members like with like (kind mixed with byKind when two dollar kinds meet); size ≤ 200
getFinding(findingId)	every field plus evidence and feedback; an alarm event, the screened window and an anomaly metric carry sentence, the item in words in plant time; a past detector fire also carries fires {count, waiting, waitingIds, peerIds, items: [{findingId, status, title, start, startText}], cut, detectorId}: every fire of its detector (same playbook, asset and detectors, else the same tag), most recently seen first (at most 200 listed, cut true when more), the ids of those waiting for review, the ids with this fire's status when it is open, confirmed, known or dismissed, else this fire alone (the ones the page's verdict is recorded on), and the detector its evidence names; an Incident trend stored as Trend of <tag path> is returned with the tag named (Trend of DCM-301 jet-cool flow, as the Findings list names it) and the path in tagPath
feedback(findingId, verdict, note=None, spanRef=None, runId=None)	{ok, status, error}: verdict confirm, dismiss, known, wrong; with runId instead, thumbs (up/down) on an Ask answer; the first confirm on an Anomaly Watch anomaly also returns proposalRunId (section 8.5)
access	what the calling Perspective session may do in the views pack, its project's views settings (views) and gatewayHealthNote (the section 8.2 line, empty unless a running Gateway Health playbook leaves the gateway's own events out)
ask(...), askAndWait(..., timeout=120)	section 8.4
askHistory(collection, assetId=None)	{aboutAsset, mine, examples, placeholder, collectionName, assetName, ok, error} (examples: up to three example questions about the asset or collection, built from the context model with no model call; placeholder: "Ask about DCM-203"; collectionName / assetName: the context model's display name and asset name, else the ids (the Ask panel's heading)) earlier answered questions about assetId by anyone, and the caller's own elsewhere in the collection; each {runId, question, askedAt (plant time), assetId, byYou}, newest first, at most 10 per list, each list showing a question once at its newest asking (case, spacing and end punctuation ignored); the ask level from a session
playbooks.list(project), playbooks.get(project, name), playbooks.put(project, name, playbook)	the project's playbooks; put is checked by the engine's own parser first and written only if it would load
contextModel.list, contextModel.get(collection), contextModel.put(collection, model, revision=None)	the models; get returns {collection, enabled, revision, model, coverage, warnings, todo, detectors} (detectors: each detector's read-time status, applied included); put with the revision replaces, without one creates
contextModel.bootstrap(collection, roots, sources=None, suggest=False)	a draft (section 7.3); writes nothing
contextModel.assetFor(alarmPath)	the assets and collections listing an alarm
contextModel.interview(collection, assetId=None, audience='engineer')	{sessionId, collection, audience, questions: [{id, text, audience, gap}], phrasedBy}; sessionId None with a message when nothing is left to ask (section 7.10); interview level from a session
contextModel.interviewAnswer(sessionId, answers)	answers a list of {id, text}; {answered, skipped, drafts, dropped, draftError, canConfirm}; once per session, by its starter or an admin
contextModel.interviewPending(collection)	{sessions, canConfirm}: answered sessions not yet saved or closed
contextModel.interviewConfirm(sessionId, drafts)	writes the given drafts (unit, normal, limits and rule fields editable) and closes the session; [] closes it without a write; {ok, saved, revision, put, closed}; admin level from a session
contextModel.securityLevels	the gateway's security levels as sorted paths, for the editor's sensitive-category pickers; from a session it needs the admin level, else an empty list
contextModel.readShape(collection, shape, start=None, end=None)	one data shape read through the collection's mapped source and checked against the data contract (section 7.6); writes nothing
documents.add(collection, filename, bytes, description=None), documents.list(collection), documents.delete(docId)	section 7.4
outputs.tagPath(collection, assetId, field)	the [Artekis] Incident tag path for an asset
detectors.list(collection, assetId=None, includeRejected=False)	the collection's detectors with status, the rule in words, the stored score (every backtest fire), live counts from their stored fire rows (fired, matched, falseAlerts, waiting, hitRate) and the fires; read level from a session
detectors.export(collection, detectorId)	the detector's tag import as JSON text (section 8.5, step 4); refused with a reason, for example an unknown or rejected detector, one with no path or no expression (stuck, rate), or a tag that fails the checks of section 8.5 step 4 (a missing parent folder, one inside a UDT instance, a path holding a different expression, an unreadable referenced tag); read level from a session
anomaly.setupDraft(collection, assetIds=None, prefill=None, project=None)	the Setup form's draft: per asset the tags that keep history and those that do not, a suggested run signal, the playbook's current settings or the defaults, Ask's prefill over them, what could not be taken (dropped), collectionName (the context model's display name, else the id; the Setup page subtitle), and watchers ([{name, enabled, own, machines, checks, schedule, text}], the playbooks already watching the collection), playbook (anomaly-watch-<collection>, the one Save writes), playbookExists, saveBlocked (only other playbooks watch it) and watchedText (one plain paragraph); read level from a session
anomaly.saveSetup(collection, setup, revision=None, project=None, runNow=False)	writes the signals into the context model at revision, then the playbook anomaly-watch-<collection>; refused 409 with nothing written while only other Anomaly Watch playbooks watch the collection; each write audited; a stale revision writes nothing; admin level from a session
report.dataset(playbook, window=None, collection=None)	a dict of Datasets for one Alarm Health run's KPIs: summary, kpis, rateTrend, rateTrendBars, priority, floods, badActors, longestActive, stale, nuisance, shifts, standing, areas, findings (its last column subjectText names each subject as the Findings list does, blank where it cannot); window None → the newest run, a date → the newest whose window ended by then, a run id → that run; under 80 ms

An event dict takes collection, asset, kind, at, window ({"value": n, "unit": "MINUTES"|"HOURS"|"DAYS"}) and data; anything else is refused. From a Perspective session, feedback, playbooks.put, contextModel.put, contextModel.bootstrap, contextModel.interview*, documents.*, report.dataset and ask check the policy's security levels; a Designer reaches only the interviews of collections whose model names its own project; a verdict's actor is the session's user, designer:<user> or script:<project>.