incident-triage/algorithms/classify_incident.card.yaml

kind: uapf.algorithm.card
id: algo.incident_triage.classify_incident
version: 1.0.0
name: Incident classifier
intent: |
  Reads the normalised payload and picks one taxonomy code from a fixed
  closed list. The classifier is LLM-backed at runtime (Claude via the
  LLM gateway) and falls back to a deterministic keyword matcher when
  the gateway is unreachable. The taxonomy code is the primary driver
  for the priority and routing DMN decisions; downstream rules treat
  this output as authoritative.
algorithm_kind: classifier

io:
  inputs:
    - id: payload
      type: object
      cardinality: single
      documentation: |
        The normalized_payload from the upstream intake.normalize step.
        At minimum {title, description?, host?, severity?}.
    - id: text
      type: string
      cardinality: single
      documentation: |
        Optional pre-flattened text. If absent, the host derives it from
        payload.title + payload.description + payload.host.
  outputs:
    - id: taxonomy_code
      type: string
      constraints:
        enum:
          - network.outage.link_down
          - network.degradation
          - network.routing
          - network.dns
          - security.incident
          - facility.power
          - storage.capacity
          - service.customer_request
          - unknown.uncategorized
      documentation: The chosen taxonomy code from the closed list above.
    - id: confidence
      type: probability
      constraints:
        minimum: 0
        maximum: 1
      documentation: Model-reported confidence; the stub fallback returns 0.75 for matched / 0.20 for unmatched.
    - id: reasoning
      type: string
      documentation: One-sentence justification (English). Persisted with the AI decision; not shown to operator by default.
    - id: label_hint
      type: string
      documentation: Human-friendly short label derived from the taxonomy code (e.g. "link_down").

implementation:
  type: external
  medium: mcp_tool
  uri: uapf-ip://capability/ai.classify@1
  hash: sha256:0000000000000000000000000000000000000000000000000000000000000000
  runtime:
    capability: ai.classify@1
    note: |
      Host-fulfilled UAPF-IP capability backed by the LLM gateway
      (default Anthropic). When LLM_PROVIDER is unavailable, the host
      falls back to a regex-driven keyword matcher that produces the
      same output shape.

determinism: stochastic
side_effects: pure
complexity:
  typical_latency_ms: 800
  max_latency_ms: 30000
failure_mode: |
  Returns taxonomy_code='unknown.uncategorized' with confidence<=0.25.
  Triage continues; the DMN priority table treats unknown as P4 default.

reference:
  legal: |
    Latvijas Republikas Datu valsts inspekcijas vadlīnijas par
    automatizētu lēmumu pieņemšanu — operators may override at any time.
  standard: |
    ITIL 4 — Incident Management practice; ISO/IEC 20000-1 — service
    management taxonomy alignment.

limitations:
  - Closed taxonomy of 9 codes — broader incident types fall to unknown.uncategorized.
  - Latvian and English input supported; mixed-locale text may degrade confidence.

owners:
  - type: team
    id: openitsm-stewards
    contact: stewards@openitsm.algomation.io

lifecycle:
  status: draft

tests:
  - name: bgp-flap-network-routing
    description: |
      Edge router BGP session flapping — the classifier should pick
      network.routing, not the broader network.outage.link_down.
    inputs:
      payload:
        title: "BGP session flapping rtr-core-02 → AS6939"
        host: "rtr-core-02.lvrtc.lv"
        description: "BGP peer 198.51.100.1 toggled UP/DOWN 7 times in 12 minutes."
        severity: "high"
    expected_outputs:
      taxonomy_code: "network.routing"
  - name: customer-bandwidth-request
    description: |
      Latvian customer email asking for a bandwidth uplift — a
      service.customer_request, not a network outage.
    inputs:
      payload:
        title: "Klients SIA Latvija Tev: lūgums palielināt joslas platumu"
        description: "Mūsu uzņēmumam nepieciešams palielināt internet pieslēguma joslas platumu no 100 Mbps uz 500 Mbps."
        severity: "average"
    expected_outputs:
      taxonomy_code: "service.customer_request"
  - name: ddos-volumetric
    description: |
      Volumetric UDP flood pattern — security.incident takes precedence
      over generic network classifications even when the symptom is
      network-shaped.
    inputs:
      payload:
        title: "DDoS attack pattern detected on edge"
        description: "Volumetric UDP flood, 4.2 Gbps inbound to 192.0.2.0/24."
        severity: "critical"
    expected_outputs:
      taxonomy_code: "security.incident"