Skip to the content

DocumentationAI in OpsCommand

Operate and govern

AI in OpsCommand

What AI does, how it is evaluated, and what it never does

Stage 6 of the plan. Concept note 6, 11.4, 12 and 17; upgrades U-13 (AI that cites and never acts) and U-24 (AI models are replaceable parts).

AI in OpsCommand suggests and never acts:

  • It is off until an organisation turns it on.
  • It receives only redacted text.
  • Every output is kept with the model, its version, the records it used (as references) and how sure it was.
  • Nothing it proposes changes a record until a person accepts it.
  • Everything works with AI off.

The provider sits behind a port, so the model is a replaceable part. The owner chooses the real provider at the last stage (D-04). Until then OpsCommand is built, tested and evaluated against a stand-in model.

The port (packages/ai)

  • Model is the interface every provider implements: classify and embed so far. Each step of Stage 6 adds the task it needs. A model has a registry id (e.g. stand-in/1) and a prompt version per task.
  • The stand-in model (stand-in/1) is a set of deterministic rules in OpsCommand's own code: keywords for categories, word overlap for services, and hashed words and word pairs for similarity. It is not a language model and makes no network call. It runs only on the machine itself (region local).
  • The registry (registry.ts) maps a model id to its code. A model in the database's registry that OpsCommand has no code for is shown as not available yet and cannot be chosen.

The registry and evaluations (database, migration 0042_ai)

TableHolds
ai.modelsEach model: provider, name, version, the regions it runs in, the tasks it serves. Platform staff register models (ai.register_model); the stand-in is registered by the migration.
ai.evaluationsEach evaluation run: model, task, evaluation set and version, prompt version, cases, score, the threshold, whether it passed, who ran it. Append-only.
ai.settingsOne row per organisation; none means off. On needs ai.configure, a model ready for at least one task, and one of its regions.
ai.outputsWhat AI produced: task, model, prompt version, region, inputs as references only ({ "incident": "<uuid>", "similar": ["<uuid>", …] }), the output, its confidence, who asked, and the person's decision (accepted or rejected, once).

A model is ready for a task only while its latest evaluation for that task passed (ai.model_ready):

  • An organisation cannot turn AI on with a model that is not ready.
  • An output cannot be recorded for a task its model is not ready for.
  • A later failed evaluation stops the model being used for that task at once.

Inputs are references. ai.record_output refuses inputs that are not record kinds pointing at ids, so no text of a record is stored with an output.

AI use is in the audit chain. Each output, and each decision on it, is recorded with its task, model, prompt version, region, references and confidence. The output itself is not copied there.

Evaluation sets (packages/ai/evals)

SetTaskPasses when
classify-reports@1ClassificationThe category and the affected service are right on average in at least 80 % of 40 reports.
documents@1DraftingIn at least 90 % of 12 cases (each kind of document), the draft is built only from the incident's recorded facts, keeps unconfirmed causes as hypotheses and states the resolution it was given.
guidance-drafts@1DraftingIn at least 90 % of 10 cases (English and Norwegian), the draft rests on a source it was given, carries its advice and is in the report's language.
handover-drafts@1DraftingIn at least 90 % of 8 cases, the draft fills exactly the fields its sources support and lists every other one as missing, with a reason.
hypotheses@1DiagnosisIn at least 90 % of 10 cases, the expected cause is proposed and every hypothesis cites evidence it was given.
narratives@1NarrationIn at least 90 % of 10 cases (English and Norwegian), every statistic is described, every sentence cites the statistics it describes and uses no number they do not contain.
similar-reports@1SimilarityIn at least 85 % of 20 cases, a report about the same problem in other words is closer than one about a different problem.

The sets are written for OpsCommand's evaluations and contain no real person's report.

  • Every implemented model is evaluated against every set in CI, in the AI package's tests.
  • pnpm --filter @opscommand/ai evaluate prints the results.
  • -- --record records them in ai.evaluations (DATABASE_URL, connected as the worker).
  • The stand-in scores 0.875 on classification and 1.0 on similarity.

A set's version changes when its cases change, and a model must pass the new version too.

In the API

Ai (apps/api/src/ai.ts) is the one place features ask a model for something. It answers null in any of these cases, so every caller has its own path without AI:

  • the organisation has AI off;
  • its model is not implemented;
  • its model is not ready for the task.

Text is redacted before it reaches a model, and the answer is recorded through ai.record_output.

Route
GET /v1/organisations/{org}/ai/settingsOn or off, model and region; the models with each task's latest evaluation
PUT …/ai/settings{ enabled, modelId, region } (ai.configure)
GET …/ai/outputsThe organisation's AI log (ai.configure)
POST …/ai/outputs/{output}/decision`{ decision: accepted \rejected }`, once

On screen

Administration → AI shows whether AI is on and lists the models with their tasks and evaluations in words. For someone with ai.configure it also has the settings (Turn AI on or Turn AI off) and the AI log.

Classification of reports (6.2)

On a report, someone with reports.manage can ask for an AI classification. It suggests:

  • the service;
  • the incident category and severity;
  • related open incidents;
  • the department responsible;
  • the support workflow, with the reason.

Each part comes with its confidence. Accepting the suggestion gives the report its service and category and marks it triaged. Rejecting it changes nothing. GET /ai/acceptance and the AI page show how often suggestions were accepted, per model and prompt version.

Similar incidents and duplicate groups (6.3)

Each organisation's records are embedded by its own model and kept in ai.embeddings, by organisation. They are compared only in the database, within the organisation (ai.nearest, ai.nearest_to), and the API never reads a vector back.

  • On a report, Find similar incidents lists similar incidents and known errors.
  • In the support queue, Look for groups proposes reports that look like an open incident. An administrator confirms each group, and the reports are grouped under that incident, or rejects it.

Knowledge search and guidance (6.4)

Search by meaning on the knowledge page shows each article's standing (verified, suggested, unconfirmed). It can be limited to approved articles (verified and published).

On a report, Draft guidance from approved articles writes customer-friendly guidance only from approved articles and cites them. It is in the report's language (evaluation set guidance-drafts@1). Nothing is sent until a person has reviewed the draft and sent it as their own reply.

Diagnosis hypotheses (6.5)

On an incident, Propose possible causes gives possible causes from approved evidence only:

  • events collected into its handovers;
  • known errors;
  • verified articles;
  • earlier incidents of the same service, with their resolutions.

Each is labelled a hypothesis and cites the evidence it rests on. A hypothesis that cites nothing it was given is never shown (evaluation set hypotheses@1).

Handover drafting (6.6)

On a draft handover, Draft the empty fields fills only fields that are still empty. It works from:

  • the incident;
  • the reports grouped under it;
  • the notes of what was tried;
  • the events collected into the handover;
  • the hypotheses resting on them.

The fields are under the handover's own contract, and every field nothing supports is listed as missing, with why. Use this draft saves it through the handover's own form; nothing is saved before then (evaluation set handover-drafts@1).

A model is ready for a task only when the latest run of every evaluation set for that task passed (migration 0044_ai_readiness).

Documentation drafting (6.7)

On an incident, Draft it writes one of six documents from the incident's recorded facts only:

  • an incident summary;
  • a root-cause draft;
  • a technical investigation report;
  • a knowledge article;
  • a post-incident report;
  • a management summary.

The facts are the incident itself, its timeline, the notes of what was tried, its linked known errors, its handovers and the hypotheses AI proposed from approved evidence (6.5). Unconfirmed causes stay under Possible causes (hypotheses, not confirmed), and every document carries the recorded resolution and workaround.

A document is kept in ai.documents (migration 0045_ai_documents) with the AI output that drafted it.

  • It is labelled AI-drafted wherever it is shown until a person with incidents.manage approves it.
  • Changing its words does not approve it; it stays AI-drafted.
  • Approving or discarding it happens once and decides the AI output (accepted or rejected). A discarded document is kept, still labelled.
  • An approved article becomes a knowledge article. It is a suggestion until someone else verifies it (3.11).

The statistics come first, and they are not AI. GET /v1/organisations/{org}/trends?days=&asOf=&service= computes them from the organisation's records, as the person may see them, for the days ending at asOf (now when not given). It compares the first half of the period with the second, by the written rules of method trends@1 (apps/api/src/trends.controller.ts, METHOD):

StatisticFromShown when
Repeated failuresIncidents per serviceat least 2 in the period
Rising errorsError and critical events per serviceat least 10 in the second half, and at least twice the first
Fragile componentIncidents per componentat least 2 in the period
Possible capacity problem95th-percentile response time of the service's checksit rose by at least half, and by at least 100 ms, with at least 10 timed checks in each half
Declining reliabilityAvailability of the service's checksit fell by at least 1 percentage point, with at least 10 checks in each half
Recurring integration failuresIncidents of the integration category per serviceat least 2 in the period

Checks come from the raw results, and, for days whose raw results are gone (4.12), from the daily summaries.

  • Each statistic lists the incidents it counts and how many measurements it rests on.
  • The answer carries a digest: SHA-256 of the method, the period and every statistic with the ids it counts. The same period gives the same digest. A record added later does not change it, and a changed rule is a new method version.
  • The statistics are reproducible for as long as the records they count are kept (retention, 4.12).

The narrative comes second. POST …/trends/narrative asks the organisation's model, while it is ready to narrate, to describe the statistics of the same period:

  • Each sentence cites the statistics it describes.
  • A sentence that cites none, or uses a number they do not contain, is dropped.
  • It is labelled AI narrative, carries the statistics' digest, and is recorded with references to the services it describes.

The operations centre and every service page show the statistics. Describe these figures with AI appears only while AI is on and the model is ready to narrate.

Transparency and the AI log (6.9)

OpsCommand meets the EU AI Act's transparency duties in the product itself (Article 50; compliance register U-25):

  • Every AI result says it is AI's. Each card that shows something AI produced carries the note Made by AI. It decides nothing and changes no record; a person does. The cards are: the report's suggestion, similar records, groups of reports, the guidance draft, search by meaning, hypotheses, the handover draft, documents and the trend narrative. The note links to AI in this organisation.
  • AI in this organisation (/o/{org}/ai, GET …/ai/transparency) can be read by every member:
  • whether AI is on, with which model, provider, version and region;
  • the principles: it suggests and never acts, it receives redacted text, everything is recorded and labelled, and it can be turned off;
  • each task the model serves, what it does here, whether it is in use, and the latest run of every evaluation set;
  • its use in the last 30 days, per task, with how many outputs were accepted, rejected or not decided;
  • the labels people will see.

While AI is off it says so, and names no model.

  • The AI log (Administration → AI, ai.configure):
  • filtered by task, decision (accepted, rejected, undecided) and period (from, to);
  • downloaded for record-keeping with ?format=csv: up to 10 000 rows of id, time, task, model, prompt version, region, the references counted by kind, confidence, who asked, the decision, and when and by whom.
  • The export never carries what AI wrote.
  • "Ready" means one thing everywhere. The settings and this page take a task's readiness from the database's ai.model_ready (every evaluation set's latest run passed), not from the latest single run.

Choosing the real provider (the owner, D-04)

  1. Register the model (ai.register_model) with its provider, version, regions and tasks.
  2. Add its code to packages/ai behind the Model interface. The provider's key is held as a sealed secret, never in code.
  3. Run the evaluation sets against it in CI and record the results.
  4. Only a model that passes can be chosen by an organisation.